peterjc/flake8-rst-docstrings

flake8 plugin to validate Python docstrings as reStructuredText (RST)

flake8-rst-docstrings

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:

• https://github.com/PyCQA/pydocstyle
• https://github.com/PyCQA/flake8-docstrings

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

• http://docutils.sourceforge.net/
• https://github.com/twolfson/restructuredtext-lint

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.
RST218	Literal block expected; none found.
RST219	Inline substitution_reference start-string without end-string.
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".
RST307	Error in "XXX" directive:
RST399	Previously unseen major error, not yet assigned a unique code.

Severe or critical 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 associated 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
RST901	Failed to parse file (No longer used)
RST902	Failed to parse __all__ entry (No longer used)
RST903	Failed to lint docstring

Installation and usage

Python 3.7 or later now required. Earlier versions did support Python 2.7, use v0.0.14 if required.

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.

Normally flake8 violations are to a specific line and column. Unfortuntatley, docutils only gives us a line number, and occasionally this only points to the start of a paragraph - not the exact line with an issue.

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, RST304 and RST305 violations. You may also need to ignore RST307 if using Sphinx directives with arguments.

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,
rst-substitutions =
    version,
extend-ignore =
    RST307,
    # ...

Note that flake8 allows splitting the comma separated lists over multiple lines, and allows including of hash comment lines.

If you are using the Google Python Style you will sometimes get unwanted warnings from this plugin - particularly in the argument descriptions - as it does not use strict RST. We therefore currently suggest ignoring some of the violation codes:

[flake8]
extend-ignore =
    # Google Python style is not RST until after processed by Napoleon
    # See https://github.com/peterjc/flake8-rst-docstrings/issues/17
    RST201,RST203,RST301,

Version History

Version	Released	Changes
v0.3.0	2022-11-16	Replaced setup.py with pyproject.toml.
v0.2.7	2022-07-15	Fix where function signature occurred in docstring body.
v0.2.6	2022-06-07	Configuration option to define additional substitutions (e.g. from Sphinx) for RST305 (contribution from Andreas Thum). Requires Python 3.7 or later.
v0.2.5	2021-12-10	Ignore function signature lines at start of docstrings.
v0.2.4	2021-12-09	Fixed rare line number problem under Python 3.7 or older. Updated test framework to use pytest. Requires Python 3.6 or later.
v0.2.3	2021-05-03	Fixed line number assert in one-line docstring-only file.
v0.2.2	2021-04-30	Fixed line number problem under Python 3.8 or later. Corrected off-by-one line number in module docstrings.
v0.2.1	2021-04-23	Minor internal style change.
v0.2.0	2021-04-23	Use AST from flake8, not re-parsing with pydocstyle. Drops RST901 (internal problem with parser). Drops RST902 (checking any __all__ entry).
v0.1.2	2021-04-16	Dropped unused logging module import. Extended test coverage.
v0.1.1	2021-04-15	Explicit pygments dependency for any code blocks.
v0.1.0	2021-04-15	Import the parser from pydocstyle directly. Requires Python 3 (drops support for Python 2).
v0.0.14	2020-09-22	Adds RST307 for error in directive (eg invalid args).
v0.0.13	2019-12-26	Adds RST218 and RST219.
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 Opdebeeck).
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

Developers may install the plugin from the git repository with optional build dependencies:

$ pip install -e .[develop]

To make a new release once tested locally and on TravisCI:

$ git tag vX.Y.Z
$ python -m build
$ git push origin master --tags
$ twine upload dist/flake8?rst?docstrings-X.Y.Z*

The PyPI upload should trigger an automated pull request updating the flake8-rst-docstrings conda-forge recipe.

flake8-rst-docstrings's Issues

Replace TravisCI for continuous integration testing

Path of least resistance would be CircleCI since I am familiar with that, else GitHub actions...

Add test cases for python3.7 and python3.8

Currently both tox.ini and travis.yml do not support latest python versions.

I can send a PR with the fix!

Related: wemake-services/wemake-python-styleguide#1138

Is it possible to support Sphinx more holistically, as some kind of extension/addon?

Sphinx has a really large number of directives and roles.

I made a best-effort attempt at whitelisting them all in a .flake8 config file, assuming the py domain is set to the default, and the js, c, etc. domains are not used: https://gist.github.com/gwerbin/7a981694ae545f228e697058cff00ef3

This is a huge list, and it's not even exhaustive! It will need to be adjusted for different choices of default-domain, and it doesn't currently support any of the non-py domains. It might also go out of date between Sphinx versions.

It would be great if there was an flake8-rst-docstrings[sphinx] "extra" that could be installed to support all this. Hopefully Sphinx exposes this information in a public API that can be used for checks, instead of trying to maintain hard-coded lists like the above.

Is that something the maintainers would be interested in? Maybe someone with Sphinx development experience can comment on feasibility here.

Double reports for RST212 Title underline too short.

This is a known issue with the recently added RST212 Title underline too short., see #11.

We suspect it is a bug lower in the stack rather than in the plugin itself...

AttributeError: 'FlakesChecker' object has no attribute 'CONSTANT'

Is 3.8 supported? Tried to run this on Python 3.8 but I got the following:

/home/cristian/.local/lib/python3.8/site-packages/pycodestyle.py:113: FutureWarning: Possible nested set at position 1
  EXTRANEOUS_WHITESPACE_REGEX = re.compile(r'[[({] | []}),;:]')
multiprocessing.pool.RemoteTraceback: 
"""
Traceback (most recent call last):
  File "/usr/lib/python3.8/multiprocessing/pool.py", line 125, in worker
    result = (True, func(*args, **kwds))
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/checker.py", line 648, in _run_checks
    return checker.run_checks()
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/checker.py", line 579, in run_checks
    self.run_ast_checks()
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/checker.py", line 486, in run_ast_checks
    checker = self.run_check(plugin, tree=ast)
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/checker.py", line 435, in run_check
    return plugin['plugin'](**arguments)
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/plugins/pyflakes.py", line 90, in __init__
    super(FlakesChecker, self).__init__(tree, filename,
  File "/home/cristian/.local/lib/python3.8/site-packages/pyflakes/checker.py", line 494, in __init__
    self.handleChildren(tree)
  File "/home/cristian/.local/lib/python3.8/site-packages/pyflakes/checker.py", line 816, in handleChildren
    self.handleNode(node, tree)
  File "/home/cristian/.local/lib/python3.8/site-packages/pyflakes/checker.py", line 863, in handleNode
    handler(node)
  File "/home/cristian/.local/lib/python3.8/site-packages/pyflakes/checker.py", line 816, in handleChildren
    self.handleNode(node, tree)
  File "/home/cristian/.local/lib/python3.8/site-packages/pyflakes/checker.py", line 862, in handleNode
    handler = self.getNodeHandler(node.__class__)
  File "/home/cristian/.local/lib/python3.8/site-packages/pyflakes/checker.py", line 696, in getNodeHandler
    self._nodeHandlers[node_class] = handler = getattr(self, nodeType)
AttributeError: 'FlakesChecker' object has no attribute 'CONSTANT'
"""

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/cristian/.local/bin/flake8", line 8, in <module>
    sys.exit(main())
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/main/cli.py", line 16, in main
    app.run(argv)
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/main/application.py", line 396, in run
    self._run(argv)
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/main/application.py", line 384, in _run
    self.run_checks()
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/main/application.py", line 310, in run_checks
    self.file_checker_manager.run()
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/checker.py", line 319, in run
    self.run_parallel()
  File "/home/cristian/.local/lib/python3.8/site-packages/flake8/checker.py", line 288, in run_parallel
    for ret in pool_map:
  File "/usr/lib/python3.8/multiprocessing/pool.py", line 868, in next
    raise value
AttributeError: 'FlakesChecker' object has no attribute 'CONSTANT'

Plugin should use lines (or tree), provided by flake8

It seems, this plugin uses a hackish way to parse files by itself, instead of using provided by flake8 infrastructure. This is much like zheller/flake8-quotes#93. I believe, it's easy to fix too.

Inconsistent false positive RST214

I'm using this to make sure my rST is correct for documentation builds, but every once in a while I end up getting a weird false positive on RST214: inline literal start-string without end-string. Now it wouldn't be an issue if I could identify a cause, but I'm currently getting the warning on a piece of docstring that is an exact duplicate from elsewhere in the file.

the two functions start from this line and downwards

Wrong line numbers reported under Python 3.8 with v0.2.x

Hello

Given the following code snippet

import json


def another(x):
    """Another test function.

    This function is here to add extra lines to this snippet

    Parameters
    ----------
    x : int
        An arbitrary variable
    """
    json.loads(str(x))


# This is line 17
def f(id_):
    """Test function.

    Parameters
    ----------
    id_ : str. # This is line 23
        The identifier of the object
    """
    print("Hello world!")

I have the following flake8 configuration (nothing specific for rst-docstrings, but including for completeness' sake):

[flake8]
max_line_length = 120
max_complexity = 10
doctests = True
ignore = S101,E501,E203,W503,FS003

Python version:
Python 3.8.8

Then when I run the flake8 (with flake8-rst-docstrings==0.2.1) on the following snippet I receive:
/SCRATCHES/poc_flake8_docstrings.py:17:1: RST306 Unknown target name: "id".

when I run the flake8 (with flake8-rst-docstrings==0.1.2) on the following snippet I receive:
/SCRATCHES/poc_flake8_docstrings.py:23:1: RST306 Unknown target name: "id".

As you can observe, when using the latest version (happens for 0.2.0 as well), flake8 shows us the wrong line number.
Since I don't wan't to fix the doc, but ignore it. I now have to place a # noqa: RST306 on line 17. But in my real code, I have my function decorated, so I have to put the noqa behind an argument in my decorator and that makes no sense at all.

The behaviour is actually wrong as well, but this is mentioned in #26

If you need any more info, or if I can be of any more assistance, don't hesitate :)

Request for new error code from "RST399 Unknown target name"

RST allows definition of hyperlink references:

Here's where the hyperlink-name_ is used.

.. _hyperlink-name: Here's where the hyperlink target is defined.

When using Sphinx, I put commonly used hyperlink targets into rst_epilog in my conf.py. When running flake8-rst-docstrings, this leads to RST not knowing about these conf.py-defined targets, and I get, e.g., from this line:

tests\test_api_good.py:23:1: RST399 Unknown target name: "license_txt".

It would be good to assign this error its own code, so that I can selectively ignore them.

Verify violation line numbers in test suite

Currently tests/run_tests.sh has this code:

for code in RST??? ; do
    echo "======"
    echo $code
    echo "======"
    for file in $code/*.py ; do
        echo "flake8 --select RST $file"
        flake8 --select RST $file 2>&1 | grep ": $code "
    done
    echo "Good, $code violations reported, as expected."
done

Those examples contain in their module docstring the expected output, including line numbers, but we do not currently validate that. We'd have to move from bash to Python, but that would be worth doing at some point.

Need new validation code for Error in "XXX" directive:

Hello, I'm getting some errors when I try to set directive attributes.

You can reproduce using the example below:

class Immutable(object):
    """
    Helper type for objects that should be immutable.

    When applied, each instance becomes immutable.
    Nothing can be added or deleted from it.

    .. code:: pycon
      :force:  # HERE

      >>> from returns.primitives.types import Immutable
      >>> class MyModel(Immutable):
      ...     ...

      >>> model = MyModel()
      >>> model.prop = 1
      Traceback (most recent call last):
         ...
      returns.primitives.exceptions.ImmutableStateError

    See :class:`returns.primitives.container.BaseContainer` for examples.

    """

output:

  579:1    RST399 Error in "code" directive:
  """
        Get value from successful container or raise exception for failed one.

        .. code:: pycon
          :force:

          >>> from returns.io import IO, IOFailure, IOSuccess
          >>> assert IOSuccess(1).unwrap() == IO(1)

          >>> IOFailure(1).unwrap()
          Traceback (most recent call last):
            ...
          returns.primitives.exceptions.UnwrapFailedError

        """
  ^

More informations:

• flake8-rst-docstrings==0.0.12
• Python 3.8.3

Possible false positive for RST203

I this code that follows google-styleguide: https://google.github.io/styleguide/pyguide.html#doc-function-args

class Checker(object):
    def __init__(
        self,
        tree: ast.AST,
        file_tokens: Sequence[tokenize.TokenInfo],
        filename: str = constants.STDIN,
    ) -> None:
        """
        Creates new checker instance.

        These parameter names should not be changed.
        ``flake8`` has special API that passes concrete parameters to
        the plugins that ask for them.

        ``flake8`` also decides how to execute this plugin
        based on its parameters. This one is executed once per module.

        Arguments:
            tree: ``ast`` parsed by ``flake8``. Differs from ``ast.parse``
                since it is mutated by multiple ``flake8`` plugins.
                Why mutated? Since it is really expensive
                to copy all ``ast`` information in terms of memory.
            file_tokens: ``tokenize.tokenize`` parsed file tokens.
            filename: module file name, might be empty if piping is used.

        """

But, I have this violation raised:

» flake8 ./wemake_python_styleguide/checker.py

./wemake_python_styleguide/checker.py

  110:1    RST203 Definition list ends without a blank line; unexpected unindent.
  
  ^

But, this is considered valid:

        Arguments:
            tree: ``ast`` parsed by ``flake8``. Differs from ``ast.parse``
                since it is mutated by multiple ``flake8`` plugins.
                Why mutated? Since it is really expensive
                to copy all ``ast`` information in terms of memory.

            file_tokens: ``tokenize.tokenize`` parsed file tokens.
            filename: module file name, might be empty if piping is used.

I cannot used this, because it breaks https://github.com/terrencepreilly/darglint
I am not sure what is correct in this case.

Gives errors on well known text roles

like :class: or :func:

Add check for empty line between description and parameter list

Currently, the following code passes validation:

"""
Construct the mappings with file line numbers included.

Overrides 'yaml.constructor.SafeConstructor.construct_mapping()'.
:param node: MappingNode object.
:param deep: Deep flag.
"""

However, once rendered, this is the result:

As you can see, the parameters were not rendered correctly.

Adding an empty line to the Docstring solves this issue:

"""
Construct the mappings with file line numbers included.

Overrides 'yaml.constructor.SafeConstructor.construct_mapping()'.

:param node: MappingNode object.
:param deep: Deep flag.
"""

Output:

It would be very helpful if flake8-rst-docstrings implemented a check for this.

AssertionError: Bad start line with v0.2.2

CI link: https://github.com/wemake-services/wemake-python-styleguide/pull/2003/checks?check_run_id=2488908765

Error message:

Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/multiprocessing/pool.py", line 121, in worker
    result = (True, func(*args, **kwds))
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/multiprocessing/pool.py", line 44, in mapstar
    return list(map(*args))
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/checker.py", line 676, in _run_checks
    return checker.run_checks()
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/checker.py", line 589, in run_checks
    self.run_ast_checks()
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/checker.py", line 494, in run_ast_checks
    for (line_number, offset, text, _) in runner:
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8_rst_docstrings.py", line 193, in run
    docstring,
AssertionError: Bad start line, node line number 1 for: See :term:`preset` in the docs.

"""

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/bin/flake8", line 8, in <module>
    sys.exit(main())
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/main/cli.py", line 22, in main
    app.run(argv)
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/main/application.py", line 363, in run
    self._run(argv)
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/main/application.py", line 351, in _run
    self.run_checks()
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/main/application.py", line 264, in run_checks
    self.file_checker_manager.run()
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/checker.py", line 321, in run
    self.run_parallel()
  File "/home/runner/work/wemake-python-styleguide/wemake-python-styleguide/.venv/lib/python3.7/site-packages/flake8/checker.py", line 287, in run_parallel
    for ret in pool_map:
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/multiprocessing/pool.py", line 354, in <genexpr>
    return (item for chunk in result for item in chunk)
  File "/opt/hostedtoolcache/Python/3.7.10/x64/lib/python3.7/multiprocessing/pool.py", line 748, in next
    raise value
AssertionError: Bad start line, node line number 1 for: See :term:`preset` in the docs.

False positive RST902 (tuple without redundant parentheses)

Example:

__all__ = 'IPolys',

Unknown directive type

Hello,
I'm using the sphinxcontrib-needs extension. It brings own Sphinx directives flake8-rst-docstrings does not know about. For example, my test cases have docstrings containing a new test directive .. test:: Test invalid build spec.
So I get errors like

./tests/application/test_cli/test_cli.py:6:1: RST399 Unknown directive type "test".
./tests/application/test_input/test_input.py:9:1: RST399 Unknown directive type "test".

What are my best chances to get around this issue? Is there a configuration option to add my custom directives? Or do I have to ignore those lines or ignore RST399 completely? The documentation tells me RST399 | Previously unseen major error, not yet assigned a unique code. - I think it makes sense to have RST399 enabled if some other unseen major error shows up.

Thanks
Marco

Bug with single word on first line of docstring

I think that the line

flake8-rst-docstrings/flake8_rst_docstrings.py

Line 200 in 3551caf

docstring = docstring.replace(firstline, "")

should be changed to include a count of 1:

docstring = docstring.replace(firstline, "") -> docstring = docstring.replace(firstline, "", 1)

Otherwise it replaces other instances of firstline in the whole string. In SageMath, for example, the first line of a docstring might be "Axioms", and then any line starting with "Axioms " get changed to start with the trailing space " ", at which point the parser thinks the line is indented.

Add support for signature overloading

Sphinx' autodoc supports the ability to overload signatures, which is useful for expressing e.g. semantics which older versions of Python don't support (like positional-only arguments in code compatible with pre-3.8).

However currently this is checked like "normal" rst code and thus any signature which looks a bit like invalid rST will trigger an error e.g.

def foo(*args, **kwargs):
    """foo([thing, ][**params]) -> Thing
    """

Furthermore it is not possible to "escape" the signature, sphinx will fail to interpret a literal as a signature, and it will not apply regular escapes (backslashes) leading to incorrect rendering of the sig'.

Not working for for file with shebang line

Hey,
I have tested your extension and I find it very useful. Unfortunately, it does not work for files with shebang lines, for example:

#!/usr/bin/env python
# -*- coding: utf-8 -*-

The error message is:

RST901: Failed to parse file: encoding declaration in Unicode string

Issues with multiline arg descriptions

I am struggling with multiline Args: descriptions, i.e. the following yields RST301 and RST203 at the last line of the docstring body. The following could should be enough to reproduce the issue.

"""Test the linter."""


def test(arg1: int, arg2: int) -> None:
    """Fail the linter.

    Args:
        arg1 (int): something
        arg2 (int): something very
            long (RST301)
    """


def test2(arg1: int, arg2: int) -> None:
    """Fail the linter.

    Args:
        arg1 (int): something
            very long
        arg2 (int): something (RST203 here caused by arg1)
    """

Multiple-letter violation codes are not displayed by Vim Syntastic syntax checker

This is not a bug with your plugin but I'm raising this here for your awareness, since you use multiple-letter violation code(s).

I've filed an issue with vim-syntastic: vim-syntastic/syntastic#2163.

The resolution of that bug may be of interest to you. If not, please disregard this report, with my apologies.

RST299 Cannot analyze code. Pygments package not found.

Not sure if this deserves its own error code. Probably should just declare pygments an explicit requirement?

Reading from a closed stdin buffer error

Original issue: wemake-services/wemake-python-styleguide#871

Bug report

What's wrong

Opening a file in emacs+flycheck just raises ValueError: I/O operation on closed file.
Though it's not an issue with WPS, but with some flake8 plugins, I want this to get off from the ground somehow.

Plugins that are responsible for that:

• flake8-bandit (I already had made a PR and it was merged)
• flake8-print (JBKahn/flake8-print#36)
• flake8-debugger (JBKahn/flake8-debugger#18)
• flake8-rst-docstrings (There are no issues or pr regarding that yet.)

You can dive deeper into the topic by reading flake8-print PR.
To be able to use WPS now -- I should firstly uninstall those plugins, that's a pain.

How is that should be

It should work without errors :)

Create a test suite and use this for continuous integration

As noted in the TODO list in the main README, the current minimal test suite lacks any negative examples etc.

Identifier with trailing underscore

A variable name with a trailing underscore gives Unknown target name:

$  cat test.py 
def f(id_: str):
    """Function.

    :param id_: A string."""
    print()
$  flake8 test.py 
test.py:4:1: RST306 Unknown target name: "id".

Could this be related to sphinx issue 1462?

False positive RST206 at end of docstring?

Updated text:

Retitled to focus on this specific possible false positive at the end of a docstring:

RST206 Field list ends without a blank line; unexpected unindent.

Original text:

It seems using docutils for validation may clash with some sphinx specific extensions/conventions.

See also https://gitlab.com/pycqa/flake8/merge_requests/198#note_36943788

Request for new error code from "RST399 Undefined substitution referenced"

RST allows definition of "substitution sequences":

Here's where the |foo| substitution is used.

.. |foo| replace:: Here's where it's defined.

When using Sphinx, I put commonly used substitution sequences into rst_epilog in my conf.py. When running flake8-rst-docstrings, this leads to the per-file RST not knowing about these conf.py-defined substitutions, and so I get, e.g., from this line:

tests\test_api_good.py:4:1: RST399 Undefined substitution referenced: "objects.inv".
Sphinx |objects.inv| files.

It would be good to assign this error its own code, so that I can selectively ignore them.

Consider adding rstcheck integration

Currently this code passes our CI:

def some():
    """
    ====
    Test
    ====

    .. code:: python

        print(

    End.
    """

But, the example is clearly invalid. It should not pass the CI in my opinion.

There's a tool for that: https://github.com/myint/rstcheck
Maybe we can integrate this tool into flake8-rst-docstrings?

If it is not aligning nicely with the goal of this project, I will consider adding it directly into https://github.com/wemake-services/wemake-python-styleguide

False positive for RST213 and RST210 from *arg and **kwargs

This code produces two violations:

def include(*args: str, **kwargs) -> None:
    """
    Used for including Django project settings from multiple files.

    Args:
        *args: File paths (``glob`` - compatible wildcards can be used).
        **kwargs: Settings context: ``scope=globals()`` or ``None``.

    """

Output:

» flake8 .

./split_settings/tools.py

  65:1     RST299 Inline emphasis start-string without end-string.
  Args:
  ^

  65:1     RST210 Inline strong start-string without end-string.
  Args:
  ^

That's because flake8-rst-docstrings is unhappy about *args and **kwargs in the docs. But, napoleon and google explicitly says to write them like so, proof: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google

def module_level_function(param1, param2=None, *args, **kwargs):
    """This is an example of a module level function.

    ...

    Args:
        param1 (int): The first parameter.
        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
            Second line of description should be indented.
        *args: Variable length argument list.
        **kwargs: Arbitrary keyword arguments.
    
    ...
    """

So, I guess that these two rules should respect this case.