Можно ли иметь список параметров в sphinx.ext.napoleon?

Question

Я использую расширение autodoc sphinx вместе с sphinx.ext.napoleon. Я следую руководству по стилю numpydoc, так как считаю его более читабельным, чем руководство Google. Однако я заметил следующую проблему, которую не смог исправить.

У меня следующий вопрос. Можно ли разрешить в разделе параметров (или возврата и т. Д.) Иметь список? Я хотел бы иметь что-то вроде:

ОБНОВЛЕНИЕ Я удалил некоторые начальные проблемы в соответствии с ответом Стива Пирси. Вот файл python:

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 data frame" и "This...." одинаков. Однако я бы предпочел стиль наполеона, где все меньше и в начале нет серой линии.

И, наконец, удаление пустой строки перед точками с маркерами не помогает. Это делает это хуже:

Answer 1

Похоже, вы не следуете примеру строк документации Python стиля NumPy.

• Параметры не должны содержать пробелов в своих именах.
• Тип Python должен быть действительным (я не уверен насчет "фрейма данных панд")
• Там не должно быть пустой строки выше param 2