Skip to content
flake8 plugin to validate Python docstrings as reStructuredText (RST)
Python Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
tests
.flake8 Tell flake-quote we're using double quotes Aug 7, 2019
.gitignore
.travis.yml Simple test framework Apr 23, 2019
LICENSE.rst
MANIFEST.in
README.rst RST217 Mismatch: both interpreted text role suffix and reference suffix. Nov 18, 2019
flake8_rst_docstrings.py flake8 E501, C405 Nov 18, 2019
requirements.txt Make flake8 v3.0.0 onwards dependency explicit Jun 16, 2017
setup.cfg
setup.py

README.rst

flake8-rst-docstrings

Released on the Python Package Index (PyPI) Released on Conda Testing with TravisCI PyPI downloads Code style: black

Introduction

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 flake8-docstrings, see:

The reStructuredText (RST) validation is done by calling docutils via Todd Wolfson's restructuredtext-lint code:

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 *.rst files or the docstrings within your *.py files.

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 RST as its prefix.

Internally we use docutils for RST validation, which has this to say in PEP258:

  • 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.

The 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 flake8 codes using one hundred times the level. i.e. Validation codes RST4## are severe or critical errors in RST validation, RST3## are major errors, RST2## are warnings, and while currently not yet used, RST1## would be information only.

Warning codes:

Code Description
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:

Code Description
RST301 Unexpected indentation.
RST302 Malformed table.
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:

Code Description
RST401 Unexpected section title.
RST499 Previously unseen severe error, not yet assigned a unique code.

Codes ending 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.

Codes starting 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 flake8 which 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 like RST2 meaning RST200, RST201, ... and so on.

Configuration

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 false positive RST303 and RST304 violations.

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 flake8 configuration, for example in your .flake8, setup.cfg, or 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.

Version History

Version Released Changes
v0.0.12 2019-11-18
  • Adds RST213 to RST217.
v0.0.11 2019-08-07
  • Configuration options to define additional directives and roles (e.g. from Sphinx) for RST303 and RST304.
v0.0.10 2019-06-17
  • Fixed flake8 "builtins" parameter warning (contribution from Ruben, @ROpdebee).
v0.0.9 2019-04-22
  • Checks positive and negative examples in test framework.
  • Adds RST212, RST305 and RST306 (contribution from Brian Skinn).
v0.0.8 2017-10-09
  • Adds RST303 and RST304 for unknown directives and interpreted text role as used in Sphinx-Needs extension.
v0.0.7 2017-08-25
  • Remove triple-quotes before linting, was causing false positives reporting RST entries ending without a blank line at end of docstrings (bug fix for issue #1).
v0.0.6 2017-08-18
  • Support PEP263 style encodings following a hashbang line (bug fix for issue #2).
v0.0.5 2017-06-19
  • Support PEP263 style encoding declaration under Python 2.
  • Introduced RST900 when fail to open the file.
v0.0.4 2017-06-19
  • Catch docstring linting failures, report as RST903.
v0.0.3 2017-06-16
  • Ensure plugin code and RST files themselves validate.
  • Removed unused import of six module.
  • Basic continuous integration checks with TravisCI.
v0.0.2 2017-06-16
  • Explicitly depend on flake8 v3.0.0 or later.
  • Improved documentation.
v0.0.1 2017-06-16
  • Initial public release.

Developers

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.

TODO

  • Have the "INFO" level RST1## codes available but ignored by default?
  • Can we call docutils rather 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.
You can’t perform that action at this time.