Я использую расширение sphinx autodoc вместе с sphinx.ext.napoleon. Я следую руководству по стилю numpydoc, так как считаю его более читабельным, чем у Google. Однако я заметил следующую проблему, которую не смог исправить.
У меня следующий вопрос. Можно ли разрешить в разделе «Параметры» (или «Возвраты» и т. д.) иметь список? Я хотел бы иметь что-то вроде:
ОБНОВЛЕНИЕ Я удалил некоторые первоначальные проблемы в соответствии с ответом Стива Пирси. Вот файл питона:
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
К сожалению, это по-прежнему вызывает проблему, заключающуюся в том, что шрифт «Это будет ...» слишком велик и не помещается рядом с param_1, как для param_2:
Если я удалю маркированный список, я получу правильно выглядящий результат. Изменение приведенного выше кода на:
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
что приводит к следующему правильному выводу:
Файл .rst для создания документации выглядит просто:
.. automethod:: test.Test.f
Если я использую numpydoc вместо sphinx.ext.napleon, кажется, я получаю правильный вывод:
по крайней мере, шрифт «кадра данных pandas» и «This....» одинаков. Однако я бы предпочел стиль Наполеона, где все меньше и нет серой линии в начале.
Наконец, удаление пустой строки перед маркерами не помогает. Делает хуже:
