Заставить autodoc sphinx показывать значения по умолчанию в описании параметров

У меня есть следующая строка документации:

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» в описание параметров, если она доступна?


python python-sphinx autodoc
person iTayb    schedule 29.06.2013    source источник

Ответы (4)


arrow_upward
3
arrow_downward

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]
"""
person Samuel Marks    schedule 19.07.2020

arrow_upward
3
arrow_downward

Я принял ответ Воя и создал пакет, который автоматически делает это за вас. Вы можете попробовать его и сообщить о проблемах.

Следующий код

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.

person zwang    schedule 31.03.2021

arrow_upward
2
arrow_downward

Это невозможно и должно выполняться вручную.

person iTayb    schedule 23.08.2013
comment
Это очень возможно. - person W4t3randWind; 20.03.2018
comment
@ W4t3randWind было бы неплохо, если бы вы опубликовали ответ, который на самом деле говорит, как тогда - person Tommy; 03.05.2018
comment
Это был просто ехидный комментарий, что авторы исключили эту функцию. Это возможно, просто Sphinx не поддерживает эту функцию. - person W4t3randWind; 03.05.2018

arrow_upward
0
arrow_downward

Хотя это все еще вручную, это один из методов, который я использую для более четкой стилизации значений аргументов по умолчанию:

пример этого метода

Добавлена ​​замена 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 изначально поддерживал значения параметров по умолчанию.

person Voy    schedule 11.07.2020