python - 使 sphinx 的 autodoc 在参数描述中显示默认值

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”部分添加到参数的描述中？

Answer 1

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]
"""

Answer 2

我采用了 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.

Answer 3

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

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 原生支持默认参数值会很不舒服。