Make sphinx's autodoc show default values in parameters' description

Question

I have the following docstring:

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
    '''

Is there a way to tell sphinx to add the "Default is X" part to the parameters' description if available?

score 5 · Answer 1 · answered Mar 31 '21 at 15:39

I have adopted Voy's answer and made a package which automatically does this for you. You are very welcome to try it and to report issues.

The following code

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

will be rendered like this if the default theme is used, and like this with sphinx_rtd_theme.

score 4 · Accepted Answer · answered Jul 19 '20 at 14:43

defaults to is the keyword now. See 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]
"""

score 2 · Answer 3 · answered Aug 23 '13 at 09:17

2

This is not possible and must be done manually.

answered Aug 23 '13 at 09:17

iTayb

12,373
24
81
135

1

This is very possible. – W4t3randWind Mar 20 '18 at 17:39
10

@W4t3randWind would be nice if you posted an answer that actually tells is how then – Tommy May 03 '18 at 14:59
It was just a snide comment that the authors excluded this feature. It's *possible* it's just not a feature Sphinx supports. – W4t3randWind May 03 '18 at 18:41

score 1 · Answer 4 · answered Jul 11 '20 at 06:29

While it is still manual, this is one method I use to stylize the default argument values more distinctly:

Added a ReST substitution: (Where to put it?)

.. |default| raw:: html

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

Then used it in docstring:

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

and a little styling through custom CSS:

(note that you may need to add some extra rules to this CSS to override the styling of your theme, for instance: html.writer-html5 .rst-content ul.simple li worked for me)

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

Note that I haven't tested this method with multiple Sphinx themes and it may need adjustments for other themes. Tested with sphinx_rtd_theme theme. Also note that this relies on HTML closing that first <div> automatically which is a bit naughty. Would be sick for ReST to support default parameter values natively.

Make sphinx's autodoc show default values in parameters' description

4 Answers4