Fix duplicated *args and **kwargs with autodoc_typehints

[AntoineD]

Fix duplicated *args and **kwargs with autodoc_typehints

Bugfix

• Bugfix

Detail

Consider this

class _ClassWithDocumentedInitAndStarArgs:
    """Class docstring."""

    def __init__(self, x: int, *args: int, **kwargs: int) -> None:
        """Init docstring.

        :param x: Some integer
        :param *args: Some integer
        :param **kwargs: Some integer
        """

when using the autodoc extension and the setting autodoc_typehints = "description".

WIth sphinx 4.2.0, the current output is

Class docstring.

   Parameters:
      * **x** (*int*) --

      * **args** (*int*) --

      * **kwargs** (*int*) --

   Return type:
      None

   __init__(x, *args, **kwargs)

      Init docstring.

      Parameters:
         * **x** (*int*) -- Some integer

         * ***args** --

           Some integer

         * ****kwargs** --

           Some integer

         * **args** (*int*) --

         * **kwargs** (*int*) --

      Return type:
         None

where the *args and **kwargs are duplicated and incomplete.

The expected output is

  Class docstring.

   Parameters:
      * **x** (*int*) --

      * ***args** (*int*) --

      * ****kwargs** (*int*) --

   Return type:
      None

   __init__(x, *args, **kwargs)

      Init docstring.

      Parameters:
         * **x** (*int*) -- Some integer

         * ***args** (*int*) --

           Some integer

         * ****kwargs** (*int*) --

           Some integer

      Return type:
         None

[tk0miya]

This change will cause the :param: definition without prefixes (ex. args, kwargs). So this change is not good. I think it would be better to change modify_field_list() and augment_descriptions_with_types() instead (without modifying this annotation data).

[tk0miya]

I noticed this docstring causes warnings because * and ** are considered as mark-up symbols:

    def __init__(self, x: int, *args: int, **kwargs: int) -> None:
        """Init docstring.

        :param x: Some integer
        :param *args: Some integer
        :param **kwargs: Some integer
        """

Here are warnings:

/Users/tkomiya/work/tmp/doc/example.py:docstring of example.ClassWithDocumentedInitAndStarArgs:6: WARNING: Inline emphasis start-string without end-string.
/Users/tkomiya/work/tmp/doc/example.py:docstring of example.ClassWithDocumentedInitAndStarArgs:7: WARNING: Inline strong start-string without end-string.

It will work fine if we escape * character like the following. But it's not officially recommended way, I believe.

    def __init__(self, x: int, *args: int, **kwargs: int) -> None:
        """Init docstring.

        :param x: Some integer
        :param \*args: Some integer
        :param \*\*kwargs: Some integer
        """

I'm not sure this feature is really needed?

[AntoineD]

I noticed this docstring causes warnings because * and ** are considered as mark-up symbols:

    def __init__(self, x: int, *args: int, **kwargs: int) -> None:
        """Init docstring.

        :param x: Some integer
        :param *args: Some integer
        :param **kwargs: Some integer
        """

Here are warnings:

/Users/tkomiya/work/tmp/doc/example.py:docstring of example.ClassWithDocumentedInitAndStarArgs:6: WARNING: Inline emphasis start-string without end-string.
/Users/tkomiya/work/tmp/doc/example.py:docstring of example.ClassWithDocumentedInitAndStarArgs:7: WARNING: Inline strong start-string without end-string.

It will work fine if we escape * character like the following. But it's not officially recommended way, I believe.

    def __init__(self, x: int, *args: int, **kwargs: int) -> None:
        """Init docstring.

        :param x: Some integer
        :param \*args: Some integer
        :param \*\*kwargs: Some integer
        """

I'm not sure this feature is really needed?

This is needed for the Numpy and Google docstring formats, which napoleon converts to :param:s.

[tk0miya]

Oh, I missed numpydoc format. Indeed, it recommends prepending stars.
https://numpydoc.readthedocs.io/en/latest/format.html#parameters

[tk0miya]

I merged #10451 instead of this. Thank you for your proposal and contribution!