This is an MIT licensed flake8 plugin for validating Python docstrings markup
as reStructuredText (RST) using the Python library
docutils. It is
available to install from the Python Package Index (PyPI):
This is based heavily off
pydocstyle (which is also MIT licensed), which
has a flake8 plugin called
The reStructuredText (RST) validation is done by calling
I recommend you also install the related flake8-docstrings plugin, which brings the pydocstyle checks into flake8. This checks things like missing docstrings, and other recommendations from PEP 257 Docstring Conventions.
You may also wish to install the related flake8 plugin flake8-rst which can check the Python style
of doctest formatted snippets of Python code within your
or the docstrings within your
Flake8 Validation codes
Early versions of flake8 assumed a single character prefix for the validation
codes, which became problematic with collisions in the plugin ecosystem. Since
v3.0, flake8 has supported longer prefixes therefore this plugin uses
as its prefix.
Internally we use
docutils for RST validation, which has this to say in
- Level-0, "DEBUG": an internal reporting issue. There is no effect on the processing. Level-0 system messages are handled separately from the others.
- Level-1, "INFO": a minor issue that can be ignored. There is little or no effect on the processing. Typically level-1 system messages are not reported.
- Level-2, "WARNING": an issue that should be addressed. If ignored, there may be minor problems with the output. Typically level-2 system messages are reported but do not halt processing
- Level-3, "ERROR": a major issue that should be addressed. If ignored, the output will contain unpredictable errors. Typically level-3 system messages are reported but do not halt processing
- Level-4, "SEVERE": a critical error that must be addressed. Typically level-4 system messages are turned into exceptions which halt processing. If ignored, the output will contain severe errors.
docutils "DEBUG" level messages are not reported, and the plugin
currently ignores the "INFO" level messages.
Within each category, the individual messages are mapped to
using one hundred times the level. i.e. Validation codes
severe or critical errors in RST validation,
RST3## are major errors,
RST2## are warnings, and while currently not yet used,
be information only.
|RST201||Block quote ends without a blank line; unexpected unindent.|
|RST202||Bullet list ends without a blank line; unexpected unindent.|
|RST203||Definition list ends without a blank line; unexpected unindent.|
|RST204||Enumerated list ends without a blank line; unexpected unindent.|
|RST205||Explicit markup ends without a blank line; unexpected unindent.|
|RST206||Field list ends without a blank line; unexpected unindent.|
|RST207||Literal block ends without a blank line; unexpected unindent.|
|RST208||Option list ends without a blank line; unexpected unindent.|
|RST210||Inline strong start-string without end-string.|
|RST211||Blank line required after table.|
|RST212||Title underline too short.|
|RST213||Inline emphasis start-string without end-string.|
|RST214||Inline literal start-string without end-string.|
|RST215||Inline interpreted text or phrase reference start-string without end-string.|
|RST216||Multiple roles in interpreted text (both prefix and suffix present; only one allowed).|
|RST217||Mismatch: both interpreted text role suffix and reference suffix.|
|RST299||Previously unseen warning, not yet assigned a unique code.|
Major error codes:
|RST303||Unknown directive type "XXX".|
|RST304||Unknown interpreted text role "XXX".|
|RST305||Undefined substitution referenced: "XXX".|
|RST306||Unknown target name: "XXX".|
|RST399||Previously unseen major error, not yet assigned a unique code.|
Severe or critial error codes:
|RST401||Unexpected section title.|
|RST499||Previously unseen severe error, not yet assigned a unique code.|
99, for example
RST499, indicate a previously unseen
validation error for which we have yet to assign a unique validation code
in the assocated range, which would be
RST4## in this example. If you see
one of these codes, please report it on our GitHub issue tracker, ideally with
an example we can use for testing.
RST9## indicate there was a problem parsing the Python
file in order to extract the docstrings, or in processing the contents.
|Code||Description (and notes)|
|RST900||Failed to load file (e.g. unicode encoding issue under Python 2)|
|RST901||Failed to parse file|
|RST902||Failed to parse __all__ entry|
|RST903||Failed to lint docstring (e.g. unicode encoding issue under Python 2)|
Installation and usage
Python 3.6 or later is recommended, but Python 2.7 and Python 3.3 onwards are also supported.
We recommend installing the plugin using pip, which handles the dependencies:
$ pip install flake8-rst-docstrings
Alternatively, if you are using the Anaconda packaging system, the following command will install the plugin with its dependencies:
$ conda install -c conda-forge flake8-rst-docstrings
The new validator should be automatically included when using
may now report additional validation codes starting with
RST (as defined
above). For example:
$ flake8 example.py
You can request only the
RST codes be shown using:
$ flake8 --select RST example.py
Similarly you might add particular RST validation codes to your flake8 configuration file's select or ignore list.
Note in addition to the
RST prefix alone you can use partial codes
RST201, ... and so on.
We assume you are familiar with flake8 configuration.
If you are using Sphinx or other extensions to reStructuredText, you will
want to define any additional directives or roles you are using to avoid
You can set these at the command line if you wish:
$ flake8 --rst-roles class,func,ref --rst-directives envvar,exception ...
We recommend recording these settings in your
for example in your
tox.ini file, e.g.:
[flake8] rst-roles = class, func, ref, rst-directives = envvar, exception,
Note that flake8 allows splitting the comma separated lists over multiple lines, and allows including of hash comment lines.
This plugin is on GitHub at https://github.com/peterjc/flake8-rst-docstrings
To make a new release once tested locally and on TravisCI:
$ git tag vX.Y.Z $ python setup.py sdist --formats=gztar $ twine upload dist/flake8-rst-docstrings-X.Y.Z.tar.gz $ git push origin master --tags
The PyPI upload should trigger an automated pull request updating the flake8-rst-docstrings conda-forge recipe.
- Have the "INFO" level
RST1##codes available but ignored by default?
- Can we call
docutilsrather than bundle a copy of their parser code?
- Create a full test suite and use this for continuous integration.
- Test with raw mode docstrings and slash-escaped characters.