Add built-in validation checks for directive syntax
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
Issue/bug
Currently, the following invalid directive syntax is not checked by numpydoc-validation
.. directive::
Some text
The numpydoc-validation checks will pass, but the invalid syntax will result in a documentation build failure with a warning and/or error such as:
WARNING: Explicit markup ends without a blank line; unexpected unindent.
ERROR: Content block expected for the "note" directive; none found.
The correct syntax, according to the reST documentation, is:
+-------+-------------------------------+
| ".. " | directive type "::" directive |
+-------+ block |
| |
+-------------------------------+
Therefore, in the first example provided above, the errors/warnings are resolved by indenting the block of text, i.e.:
.. directive::
Some text
Here is an example build failure and the subsequent commit diff with added indentation which resolved the warnings and errors and resulted in a successful documentation build. Ideally, this invalid syntax would have been caught by a pre-commit hook such as numpydoc-validation so that it could be addressed before running CI testing to avoid the inevitable documentation build failure.
This appears to be a somewhat common problem, e.g. reported here and here.
Feature request
The feature request is to add additional validation check(s) for the correct syntax of directives, e.g. add a new mapping to the existing checks, something like:
- "GL11": "reST directives {directives} text block must be indented."
Thank you for your time.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the existing built-in validation checks linked in the issue and compare their behavior with the invalid and corrected directive examples. Add validation for an unindented directive content block, ensuring the proposed diagnostic is reported while correctly indented syntax passes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100