1

I'm wondering how I can achieve the following. I'm using the numpy docstring style in combination with sphinx autodoc to generate automated documenation. However, I'm struggeling in having a nested list in the output:

Attributes
----------
attribute 1: pandas data frame
    * `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'
attribute 2: `int`
    nice and sunny days in California

the output of this docstring is complete off. It doesn't recognize the list for attribute 1.

For another thing the function description spans multiple lines:

def generate_temp(self, n, freq, very_long_variable_name,
                  type_temp=None, method=None):

Also here sphinx doesn't recognize the complete function and treats the second line independently from the first.

What is wrong with my formatting?

mzjn
  • 48,958
  • 13
  • 128
  • 248
math
  • 1,868
  • 4
  • 26
  • 60

1 Answers1

2

With NumPy docstrings in Napoleon, you need a space on both sides of the colon. Try this:

Attributes
----------
attribute 1 : pandas data frame
    * `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'
attribute 2 : `int`
    nice and sunny days in California

I don't know if that will work, as the example NumPy strings indicates that only paragraphs are supported. It doesn't mention anything about lists.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • 1
    thanks for your answer. Unfortunately, this does not solve the problem. I'm really wondering if its possible to include a list in such a case – math Sep 20 '17 at 07:34
  • Did you at least put a space on both sides of the colon? Also I looked at the [source code](https://bitbucket.org/RobRuana/sphinx-contrib/src/a311ef7908cb1cca880dcc32aae89a297ab21e0c/napoleon/sphinxcontrib/napoleon/docstring.py?at=default&fileviewer=file-view-default#docstring.py-28), and it appears that bulleted lists are supported. I think there is an issue with the indent for the second line of the first item, which I just fixed with an edit. – Steve Piercy Sep 20 '17 at 11:12