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

[sobolevn]

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.

[peterjc]

That does seem to be a conflict - https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy and https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html agree, but to me they look malformed.

Perhaps the extension special cases it? If so, we could do the same in RST210 and whatever unique code I should give for strong (since RST299 is a place holder).

[sobolevn]

Sorry, I didn't quite get the "special cases" part. What do you suggest?

[peterjc]

The following is clearly wrong in RST:

*emphasis
**strong

Yet the extensions seem to recommend this:

*args
**kwargs

Perhaps the extension does something special with these two words?

Also, I see I am missing a bunch of related messages like:

• Inline literal start-string without end-string.
• Inline interpreted text or phrase reference start-string without end-string.

See:

https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/parsers/rst/states.py

[sobolevn]

Oh, I see. The notation of *args and **kwargs is incorrect rst syntax.
I have also seen \*args and \*\*kwargs here: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google

[peterjc]

Yes, the following are fine - escaping with slashes, or wrapping with back-ticks:

If \*args or \*\*kwargs are accepted,
they should be listed as ``*args`` and ``**kwargs``.

Perhaps it is worth opening an issue with the docstring extension to double check their intent.

[peterjc]

I've released v0.0.12, so now instead of RST299 (ending 99 indicating a previously unseen error), you should get RST213.

[peterjc]

I've recently tried the plugin on two large projects with lots of these false positives:

rigetti/pyquil#1141
astropy/astropy#9820

Do you think it should ignore *args and **kwargs by default?

Or, should there be configurable lists of variable names to ignore (since not all projects will use these exact conventions)?

[sobolevn]

Yes, args and kwargs can probably be exceptional.

[peterjc]

I don't see an easy way to fix this (a docutils expert might), but have a hack on PR #27 which might be worth testing?

[knoppo]

Hey, I stumbled over this, too and I think its worth mentioning that sphinx.ext.napoleon seems to auto-escape asterisks at the beginning of each argument. See https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/ext/napoleon/docstring.py#L326

Oh, I see. The notation of *args and **kwargs is incorrect rst syntax.
I have also seen \*args and \*\*kwargs here: https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html#example-google

You can actually find both notations in there. The asterisks are escaped everywhere except in the Args: section.

Considering this, I think it would be perfectly fine to treat them as special cases just like the napoleon extension does.

[peterjc]

Thanks for the pointer to the napoleon special casing code - I agree, it would be practical to follow their example.

[sobolevn]

Related wemake-services/wemake-python-styleguide#1725

[peterjc]

I did update the README to suggest the following configuration if using the Google style:

[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,

This is still not ideal from a usability point of view. Actually applying the napoleon transformation does seem the like best approach, but it adds complexity.

[argunv]

I added * in the end of *args ... *. It helps.