Proposing a plugin for validating docstrings as reStructuredText (RST)
I am proposing a new flake8
plugin for validating docstrings as reStructuredText (RST).
Use-case
I would like to be able to validate the markup used in Python docstrings, specifically as reStructuredText (aka RST, which as per PEP287 https://www.python.org/dev/peps/pep-0287/ is recommended).
A tool able to lint the docstring RST markup could be used as part of a git pre-commit hook and continuous integration setup, and catch issues which would otherwise only be found when rendering the docstrings into browsable documentation (e.g. with epydoc or Sphinx).
Background
In https://github.com/PyCQA/pydocstyle/pull/254 I implemented a proof-of-principle extension to pydocstyle
(which is available in flake8
via the flake8-docstring
plugin) to validate Python docstrings as reStructuredText (RST) using docutils
. The pydocstyle
authors recommended writing this as a flake8
plugin rather than extending pydocstyle
itself.
Note my work was based on public domain code by Todd Wolfson in his tool restructuredtext-lint
https://github.com/twolfson/restructuredtext-lint/blob/master/restructuredtext_lint/lint.py having first established he did not wish his tool to be extended to validate Python docstrings https://github.com/twolfson/restructuredtext-lint/issues/34
Questions
Are there conventions on plugin naming I should be aware of? Would any of flake8-restructuredtext
or flake8-rst
or flake8-rst-docstring
be fine?
Are there conventions on the error code naming I should be aware of? It seems other plugins pick a currently unused single upper case letter for this (e.g. D101
from flake8-docstring
). Could an RST validator use the prefix R
(e.g. R101
, R102
, ...) or is that taken?
What would be the best existing plugin to use as a guide for writing this? Perhaps flake8-docstring
itself?