python-sphinx - 是否可以在 sphinx.ext.napoleon 中提供参数列表？

Question

我正在使用 sphinx autodoc 扩展和 sphinx.ext.napoleon。我正在遵循 numpydoc 风格指南，因为我认为它比谷歌的更具可读性。但是，我注意到以下我无法解决的问题。

我有以下问题。是否可以允许在参数部分(或返回等)中有一个列表？我想要一些类似的东西:

更新 根据 Steve Piercy 的回答，我删除了一些初始问题。这是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

您似乎没有关注 example NumPy Style Python Docstrings .

参数名称中不应包含空格。

Python 类型应该是有效的(我不确定“pandas 数据框”

param 2上面不应该有空行