Validating docstrings in Python files as RST

[peterjc]

As I understand it, rst-lint *.rst works great on plain text files using reStructuredText.

I would like to be able to do rst-lint *.py and have it pull out the Python docstrings, and check if they are valid reStructuredText.

Ideally any errors would retain the original line number from the Python file. That can probably be done via an offset if processing each docstring alone.

[twolfson]

I would like to keep this module as 1 thing well and defer to using a bash/Python glue script for that behavior. I don't know any programs off the top of my head to pull out docstrings but I'm sure they exist due to automated documentation creation. An example script would look like:

for file in *.py; do
  extract-docstrings "$file" | rst-lint -
done

[peterjc]

OK, if we discover such a extract-docstrings tool, then it would be good to add an example like this to the documentation for your tool.

[twolfson]

Yea, I would be open to adding that in the "Examples" section 👍

[peterjc]

In pull request PyCQA/pydocstyle#254 I wrote a proof-of-principle extending pydocstyle to validate Python docstrings as RST using the approach from Todd's restructuredtext-lint code.

However, the pydocstyle team recommend this functionality instead be written as a new plugin for flake8 - see https://gitlab.com/pycqa/flake8/issues/337

[twolfson]

Both make sense (i.e. flake8 plugin, CLI tool) but it seems that both pydocstyle and myself concur that it should be another library that finds/extracts the docstrings for comparison

[peterjc]

I've started working on this as a flake8 plugin under the name flake8-rst-docstrings,

https://github.com/peterjc/flake8-rst-docstrings

[peterjc]

I've made the first release of the new plugin flake8-rst-docstrings on PyPI, which uses restructuredtext-lint internally:

https://pypi.python.org/pypi/flake8-rst-docstrings

(I'll stop commenting on this issue now - thanks)