If you read further in the document you linked it looks like there's no one standard style:

Optional keyword parameters have default values, which are displayed as part of the function signature. They can also be detailed in the description:

Description of parameter `x` (the default is -1, which implies summation
over all axes).

When a parameter can only assume one of a fixed set of values, those values can be listed in braces, with the default appearing first:

order : {'C', 'F', 'A'}
    Description of `order`.

I would recommending picking a style for your own project and sticking to it.

Answer from Wayne Werner on Stack Overflow
🌐
Python-sprints
python-sprints.github.io › pandas › guide › pandas_docstring.html
pandas docstring guide — Python documentation
Instead of “str, default None”, it is preferred to write “str, optional”. When None is a value being used, we will keep the form “str, default None”. For example, in df.to_csv(compression=None), None is not a value being used, but means that compression is optional, and no compression ...
Discussions

Python docstring: some default arguments values are missing
SWIG is a software development tool that connects programs written in C and C++ with a variety of high-level programming languages. - swig/swig More on github.com
🌐 github.com
11
June 7, 2018
syntax to document default values
The numpydoc format guide says this about default values: Optional keyword parameters have default values, which are displayed as part of the function signature. They can also be detailed in the de... More on github.com
🌐 github.com
4
July 15, 2020
coding style - What are the most common Python docstring formats? - Stack Overflow
Parameters ---------- first : ... by default 'value' Returns ------- string a value in a string Raises ------ KeyError when a key error OtherError when an other error """ It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not ... More on stackoverflow.com
🌐 stackoverflow.com
Revisiting attribute docstrings - Ideas - Discussions on Python.org
PEP 224 (Attribute Docstrings) proposed a syntax for class attribute docstrings: class A: b = 42 """Some documentation.""" c = None This was rejected because of ambiguity for readers about which attribute the docstring referred to. With the prevalence of Sphinx, it is now understood that the ... More on discuss.python.org
🌐 discuss.python.org
14
October 17, 2023
🌐
Reddit
reddit.com › r/learnpython › how to doc string mutable default arguments?
r/learnpython on Reddit: How to doc string mutable default arguments?
April 16, 2023 -

I am well aware that one should avoid mutable default arguments as they are initialized once at definition and can then get mutated leading to unexpected results.

So the usual way to go is to use None as the default and then check in the body for it and assign the "actual" default there.

Now my question is if there is a recommended way to handle this in the doc string.

For example tools that build doc string templates from type hints would also declare the default value is None.

The other option would be to use the "actual" default that is eventually used in the main body

🌐
GitHub
github.com › mkdocstrings › mkdocstrings › discussions › 527
How to indicate correct default values in mkdocstring · mkdocstrings/mkdocstrings · Discussion #527
Another possible solution could be to add a docstring section: def f(a = None): """ Args: a (int | None): Description. Defaults: a: 2 """
Author: mkdocstrings
🌐
InformIT
informit.com › articles › article.aspx
Item 36: Use None and Docstrings to Specify Dynamic Default Arguments | Functions | InformIT
The convention for achieving the desired result in Python is to provide a default value of None and to document the actual behavior in the docstring (see Item 118: “Write Docstrings for Every Function, Class, and Module” for background).
🌐
Readthedocs
numpydoc.readthedocs.io › en › latest › format.html
Style guide — numpydoc v1.11.1.dev1+gca74aae44 Manual
When referring to a parameter anywhere within the docstring, enclose its name in single backticks. For the parameter types, be as precise as possible. Below are a few examples of parameters and their types. Parameters ---------- filename : str copy : bool dtype : data-type iterable : iterable object shape : int or tuple of int files : list of str · If it is not necessary to specify a keyword argument, use optional: ... Optional keyword parameters have default values, which are displayed as part of the function signature.
🌐
GitHub
github.com › swig › swig › issues › 1271
Python docstring: some default arguments values are missing
June 7, 2018 - %module test �ature(autodoc,0); �ature("compactdefaultargs"); %inline %{ const int MY_CONST_INT_VALUE = 1; int do_something(int foo, int bar=MY_CONST_INT_VALUE); #define MY_DEFINED_VALUE 2 int do_something_else(int foo, int bar=MY_DEFINED_VALUE); %} Using SWiG 2.0.12 and grepping for the docstring, would yield: aundro@flatiron:/tmp$ ${SWIG2_HOME}/bin/swig -I${SWIG2_HOME}/share/swig/2.0.12/python -I${SWIG2_HOME}/share/swig/2.0.12 -c++ -python -o test-swig2.cpp test.i aundro@flatiron:/tmp$ grep do_something test.py | grep "\->" """do_something(foo, bar=MY_CONST_INT_VALUE) -> int""" """do_something_else(foo, bar=2) -> int""" aundro@flatiron:/tmp$
Author: swig
🌐
Software Testing Help
softwaretestinghelp.com › home › python › python docstring: documenting and introspecting functions
Python Docstring: Documenting And Introspecting Functions
April 1, 2025 - This is commonly done in Python decorators. ... Answer: A docstring is the first string literal enclosed in triple-double quotes (“””), and immediately follows a class, module, or function’s definition. A docstring generally describes what the object is doing, its parameters, and its return value.
Find elsewhere
🌐
Python
peps.python.org › pep-0257
PEP 257 – Docstring Conventions | peps.python.org
Python is case sensitive and the argument names can be used for keyword arguments, so the docstring should document the correct argument names. It is best to list each argument on a separate line. For example: def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the imaginary part (default 0.0) """ if imag == 0.0 and real == 0.0: return complex_zero ...
🌐
Lsst
developer.lsst.io › python › numpydoc.html
Documenting Python APIs with docstrings — LSST DM Developer Guide main documentation
If the docstring is a single line, the terminating """ may be either on the same line or on its own line. (Be aware that PEP 257 requires that it be on the same line and black will enforce this rule.) ... """Sum numbers in an array. Parameters ---------- values : iterable Python iterable whose ...
🌐
Programiz
programiz.com › python-programming › docstrings
Python Docstrings (With Examples)
| | Parameters | ---------- | additional : str, optional | More info to be displayed (default is None) | | Returns | ------- | None | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if ...
🌐
DataCamp
datacamp.com › tutorial › docstrings-python
Python Docstrings Tutorial : Examples & Format for Pydoc, Numpy, Sphinx Doc Strings | DataCamp
February 14, 2025 - Python documentation string, commonly known as docstring, is a string literal, and it is used in the class, module, function, or method definition. Docstrings are accessible from the doc attribute (__doc__) for any of the Python objects and also with the built-in help() function.
🌐
GitHub
github.com › numpy › numpydoc › issues › 284
syntax to document default values · Issue #284 · numpy/numpydoc
July 15, 2020 - The numpydoc format guide says this about default values: Optional keyword parameters have default values, which are displayed as part of the function signature. They can also be detailed in the de...
Author: numpy
Top answer
1 of 6
1389

Formats

Python docstrings can be written following several formats as the other posts showed. However the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in this blog post.

Note that the reST is recommended by the PEP 287

There follows the main used formats for docstrings.

- Epytext

Historically a javadoc like style was prevalent, so it was taken as a base for Epydoc (with the called Epytext format) to generate documentation.

Example:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- reST

Nowadays, the probably more prevalent format is the reStructuredText (reST) format that is used by Sphinx to generate documentation. Note: it is used by default in JetBrains PyCharm (type triple quotes after defining a method and hit enter). It is also used by default as output format in Pyment.

Example:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google has their own format that is often used. It also can be interpreted by Sphinx (ie. using Napoleon plugin).

Example:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Even more examples

- Numpydoc

Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Converting/Generating

It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.

Note: The examples are taken from the Pyment documentation

2 of 6
354

The Google style guide contains an excellent Python style guide. It includes conventions for readable docstring syntax that offers better guidance than PEP-257. For example:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

I like to extend this to also include type information in the arguments, as described in this Sphinx documentation tutorial. For example:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass
🌐
Dataquest
dataquest.io › home › blog › how to use python docstrings for effective code documentation
Tutorial: Documenting in Python with Docstrings
December 13, 2024 - Default values of attributes · Python docstrings also describe the functionality and usage guidelines of small scripts, which may be appropriate for the automation of some of our daily tasks. For example, I frequently need to convert Danish kroner into euros.
🌐
Python.org
discuss.python.org › ideas
Revisiting attribute docstrings - Ideas - Discussions on Python.org
October 17, 2023 - PEP 224 (Attribute Docstrings) proposed a syntax for class attribute docstrings: class A: b = 42 """Some documentation.""" c = None This was rejected because of ambiguity for readers about which attribute the docstring referred to. With the prevalence of Sphinx, it is now understood that the docstring refers to the immediate prior symbol (see the docs).
🌐
Stack Overflow
stackoverflow.com › questions › 29272298 › storing-configuration-defaults-in-a-python-docstring
Storing configuration defaults in a Python docstring? - Stack Overflow
March 26, 2015 - I'm thinking the config specification ... the type|default|required values) config_template = """MySection: setting1: int|0 setting2: string|None|required setting3: int|10""" So far, so good. My real question is whether there's any way for me to save this config specification thing in each module in a docstring for init() ...
🌐
GitHub
gist.github.com › nipunsadvilkar › fec9d2a40f9c83ea7fd97be59261c400
What is the standard Python docstring format? · GitHub
Parameters ---------- first : array_like the 1st param name `first` second : the 2nd param third : {'value', 'other'}, optional the 3rd param, by default 'value' Returns ------- string a value in a string Raises ------ KeyError when a key error OtherError when an other error """ ... It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.
🌐
JetBrains
jetbrains.com › help › pycharm › using-docstrings-to-specify-types.html
Specify types with docstrings | PyCharm Documentation
September 1, 2025 - You debug your code permanently, and now in the course of debugging you can also collect type information and specify these types in docstrings. PyCharm provides an intention action that makes it possible to collect type information at runtime, and define type specifications. However, it is quite possible to specify the types of parameters manually, without the debugger. Both cases are explored in the section Examples. Press Ctrl+Alt+S and go to Editor | General | Smart Keys | Python.
🌐
Real Python
realpython.com › documenting-python-code
Documenting Python Code: A Complete Guide – Real Python
July 17, 2026 - Class method docstrings should contain the following: A brief description of what the method is and what it’s used for · Any arguments (both required and optional) that are passed including keyword arguments · Label any arguments that are considered optional or have a default value