Add built-in validation checks for directive syntax

[user27182]

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.

[rossbar]

Thanks for the suggestion @user27182 . Currently, the validation code is intended to validate for compliance against the numpydoc docstring format specifically. I think there's already been some scope creep, but adding general rst validation would be a significant jump. My own two cents is that an rst validation tool would be best handled in/as a separate project.