让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添加＆＃34;默认为X＆＃34;部分参数＆＃39;描述是否可用？

Answer 1

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

Answer 2

我采用了 Voy 的回答并制作了一个 package，它会自动为您执行此操作。非常欢迎您尝试并报告问题。

以下代码

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

如果使用默认主题，将像 this 一样呈现，并像 this 和 sphinx_rtd_theme 一样呈现。

Answer 3

let firstValue = pickerView.selectedRow(inComponent: 0) let secondValue = pickerView.selectedRow(inComponent: 1) 现在是关键字。参见https://github.com/sglvladi/Sphinx-RTD-Tutorial/blob/a69fd09/docs/source/docstrings.rst#the-sphinx-docstring-format

Int

Answer 4

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

---

---

添加了ReST substitution：(Where to put it?)

.. |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`
"""

和custom 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 themes，并且可能需要针对其他主题进行调整。经过sphinx_rtd_theme主题测试。还要注意，这依赖于HTML自动关闭第一个<div>，这有点顽皮。 ReST会原生支持默认参数值。