让Sphinx的自动文档显示参数描述中的默认值

Question

我有以下的文档字符串：

def progress_bar(progress, length=20):
    '''
    Returns a textual progress bar.

    >>> progress_bar(0.6)
    '[##########--------]'

    :param progress: Number between 0 and 1 describes the progress.
    :type progress: float
    :param length: The length of the progress bar in chars. Default is 20.
    :type length: int
    :rtype: string
    '''

如果有的话，是否有一种方法可以告诉sphinx将“默认为X”部分添加到参数说明中？

- iTayb

Answer 1

我采用了Voy的答案，并制作了一个软件包，可以自动为您完成此操作。欢迎您尝试并报告问题。

以下是代码：

def func(x=None, y=None):
    """
    Example docstring.

    :param x: The default value ``None`` will be added here.
    :param y: The text of default value is unchanged.
              (Default: ``'Default Value'``)
    """

    if y is None:
        y = 'Default Value'
    pass

如果使用默认主题，将呈现如此的样式，使用sphinx_rtd_theme将呈现为这个样子。

- zwang

Answer 2

defaults to 现在是一个关键词。请参见 https://github.com/sglvladi/Sphinx-RTD-Tutorial/blob/a69fd09/docs/source/docstrings.rst#the-sphinx-docstring-format

"""[Summary]

:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
"""

- Samuel Marks

Answer 3

这是不可能的，必须手动完成。

- iTayb

---

这是非常可能的。 - W4t3randWind

@W4t3randWind 如果您能发布一个真正告诉我们如何做的答案，那将是很好的。 - Tommy

这只是作者排除了这个功能的嘲讽性评论。有可能这只是Sphinx不支持的一个功能。 - W4t3randWind

Answer 4

虽然这仍然是手动的，但这是我用来更明显地为默认参数值设置样式的一种方法：

---

---

添加了一个ReST替换：(放在哪里?)

.. |default| raw:: html

    <div class="default-value-section"> <span class="default-value-label">Default:</span>

然后在文档字符串中使用它：

"""
:type host: str
:param host: Address of MongoDB host. |default| :code:`None`

:type port: int
:param port: Port of the MongoDB host. |default| :code:`None`
"""

并通过自定义CSS进行一些小的样式设置：

（请注意，您可能需要添加一些额外的规则到此CSS中，以覆盖您主题的样式，例如：html.writer-html5 .rst-content ul.simple li 对我有效）

.default-value-section {
    margin-bottom: 6px;
}
.default-value-section .default-value-label {
    font-style: italic;
}
.default-value-section code {
    color: #666;
}

请注意，我尚未测试过这种方法是否适用于多个Sphinx主题，并且可能需要对其他主题进行调整。已在sphinx_rtd_theme主题下进行了测试。还要注意的是，这依赖于HTML自动关闭第一个<div>标签，这有点不规范。希望ReST原生支持默认参数值会更好。

- Voy