Unescaped *args and **kwargs in parameter listings

[peterjc]

Both the Google and NumPy style examples are inconsistent about *args and **kwargs in parameter listings.

Quoting https://github.com/sphinx-contrib/napoleon/blob/master/docs/source/example_google.py

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

    Function parameters should be documented in the ``Args`` section. The name
    of each parameter is required. The type and description of each parameter
    is optional, but should be included if not obvious.

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

    The format for a parameter is::

        name (type): description
            The description may span multiple lines. Following
            lines should be indented. The "(type)" is optional.

            Multiple paragraphs are supported in parameter
            descriptions.

    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.

   <snip>
   """

Quoting https://github.com/sphinx-contrib/napoleon/blob/master/docs/source/example_numpy.py

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

    Function parameters should be documented in the ``Parameters`` section.
    The name of each parameter is required. The type and description of each
    parameter is optional, but should be included if not obvious.

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

    The format for a parameter is::

        name : type
            description

            The description may span multiple lines. Following lines
            should be indented to match the first line of the description.
            The ": type" is optional.

            Multiple paragraphs are supported in parameter
            descriptions.

    Parameters
    ----------
    param1 : int
        The first parameter.
    param2 : :obj:`str`, optional
        The second parameter.
    *args
        Variable length argument list.
    **kwargs
        Arbitrary keyword arguments.

   <snip>
   """

Both say the following:

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

Yet both example use a plain unescaped *args and **kwargs in the parameter sections.

Unfortunately docutils considers that malformed, raising:

• Inline emphasis start-string without end-string.
• Inline strong start-string without end-string.

i.e. incomplete single-asterisk emphasis or incomplete double-asterisk strong markup:

*emphasis
**strong

(Cross reference peterjc/flake8-rst-docstrings#18 in my flake8 plugin)

If this reflects a real limitation of the downstream parsing of the parameters, that is unfortunate. If it cannot be fixed, then I would suggest a slight clarification to the examples would help. I could write that and submit a pull request.

If this is simply a documentation oversight, should the parameter sections use a slash-escaped-asterisk?