Is it possible to have a list for a parameter in sphinx.ext.napoleon?

Question

I'm using sphinx autodoc extension together with sphinx.ext.napoleon. I'm following numpydoc style guide since I think it is more readable than google's one. However, I've noticed the following issue which I wasn't able to fix.

I have the following question. Is it possible to allow in a Parameters section (or Returns etc) to have a list? I would like to have something like:

UPDATE I've removed some initial issues according to Steve Piercy's answer. Here is the python file:

class Test:

def f(param_1, param_2):

    r"""
    This is a test docstring.

    Parameters
    ----------
    param_1 : pandas data frame
        This would be really cool to allow the following list and make
        it more readable:

        * **index:** Array-like, integer valued representing
          days. Has to be sorted and increasing.
        * **dtype:** float64. Value of temperature.
        * **columns:** location description, e.g. 'San Diego'
    param_2 : int
        nice number!
    """
    pass

Unfortunately this still gives the issue that the font of "This would be..." is too large and not placed next to param_1 as for param_2:

If I remove the bullet list I get a properly looking output. Changing the above code to:

class Test:

    def f(param_1, param_2):

        r"""
        This is a test docstring.

        Parameters
        ----------
        param_1 : pandas data frame
            This would be really cool to allow the following list and make
            it more readable: **index:** Array-like, integer valued representing
            days. Has to be sorted and increasing. **dtype:** float64. Value of temperature.
            **columns:** location description, e.g. 'San Diego'
        param_2 : int
            nice number!
        """
        pass

which leads to the following proper output:

The .rst file to generate the documentation is simply:

.. automethod:: test.Test.f

If I'm using numpydoc instead of sphinx.ext.napleon it seems I get a correct output:

at least the font of "pandas data frame" and "This...." is the same. However I would prefer the napoleon style where everything is smaller and no grey line at the beginning.

Finally also deleting the blank line before the bullet points doesn't help. It makes it worse:

Orchid

Answer 1

It looks like you are not following the example NumPy Style Python Docstrings.

• Parameters should have no spaces in their names.
• The Python type should be valid (I am uncertain about "pandas data frame"
• There should be no blank line above param 2

Ryals

many thanks for your help. I resolved your first and third bullet point and changed the "pandas data frame" to "int". However, I still get the same as in picture one above. – Orchid

Let's see the code in an update to your question, and a screenshot. Also remove any blank lines, then try removing the bullet list temporarily, just to see if that gives a proper display without the list. IOW a known good syntax example should display properly. – Ryals

I've updated my answer with the full code. Removing the bullet list works. Hope this is helpful. Many thanks for your help – Orchid

I guess that the parser chokes on the type of "pandas data frame" because it has spaces in it. Try removing spaces, "pandas.data.frame", or "pandas_data_frame". Does that help? White space matters, especially in docstrings. – Ryals

I even changed it to int as for param_2 but I get the same result (big font, and not next to the "-". – Orchid

Did you try removing the blank line before the bullet list? I'm making wild guesses here. Another help resource might be in the issue tracker for Sphinx. – Ryals

yes I did. It makes it even worse, pls see last added picture. – Orchid

Bummer. Your options are (1) dive into the source code of sphinx.ext.napoleon and Sphinx to identify and resolve the parsing and rendering, then submit a PR to fix the issue, (2) submit an issue only at the appropriate issue tracker, (3) use plain old docstring syntax without the extension, (4) live with it, or (5) something else. Sorry, I've exhausted my knowledge. – Ryals

in any case thanks for the help. really appreciated it. I might open an issue on github. – Orchid

The numpy example link is dead, is there an updated link? – Para