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:
