Readthedocs
sphinxcontrib-napoleon.readthedocs.io › en › latest › example_numpy.html
Example NumPy Style Python Docstrings — napoleon 0.7 documentation
.. _NumPy Documentation HOWTO: ... lines. The type may optionally be specified on the first line, separated by a colon. """ def function_with_types_in_docstring(param1, param2): """Example function with types documented in the docstring....
Medium
mr-amit.medium.com › numpy-docstring-explained-3d2e3b3f017a
NumPy Docstring Explained. If you think you need to spend $2,000… | by It's Amit | Medium
March 6, 2025 - A docstring is a multi-line string in Python that acts as a guide to explain what a module, function, class, or method does. Think of it as a small note left behind to make your (and everyone else’s) life easier when reading or using the code. Now, NumPy takes this concept and levels it up by creating highly structured, detailed docstrings that ensure its vast library of functions is easy to understand — even for beginners.
Readthedocs
numpydoc.readthedocs.io › en › latest › example.html
Example — numpydoc v1.11.0rc0.dev0 Manual - Read the Docs
The module’s docstring may extend over multiple lines. If your docstring does extend over multiple lines, the closing three quotation marks must be on a line by itself, preferably preceded by a blank line. example.foo(var1, var2, *args, long_var_name='hi', only_seldom_used_keyword=0, **kwargs)[source]#
Readthedocs
numpydoc.readthedocs.io › en › latest › format.html
Style guide — numpydoc v1.11.1.dev1+gca74aae44 Manual
If a method has an equivalent function (which is the case for many ndarray methods for example), the function docstring should contain the detailed documentation, and the method docstring should refer to it. Only put brief summary and See Also sections in the method docstring. The method should use a Returns or Yields section, as appropriate. Instances of classes that are part of the NumPy API (for example np.r_ np.c_, np.index_exp, etc.) may require some care.
Python-sprints
python-sprints.github.io › pandas › guide › pandas_docstring.html
pandas docstring guide — Python documentation
Parameters ---------- num1 : int First number to add num2 : int Second number to add Returns ------- int The sum of `num1` and `num2` See Also -------- subtract : Subtract one integer from another Examples -------- >>> add(2, 2) 4 >>> add(25, 0) 25 >>> add(10, -10) 0 """ return num1 + num2 ...
Sphinx
sphinx-doc.org › en › master › usage › extensions › example_numpy.html
Example NumPy Style Python Docstrings — Sphinx documentation
.. _NumPy docstring standard: https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard """ module_level_variable1 = 12345 module_level_variable2 = 98765 """int: Module level variable documented inline. The docstring may span multiple lines. The type may optionally be specified on the first line, separated by a colon. """ def function_with_types_in_docstring(param1, param2): """Example function with types documented in the docstring.
Lsst
developer.lsst.io › python › numpydoc.html
Documenting Python APIs with docstrings — LSST DM Developer Guide main documentation
For example, the description for format references the should_plot parameter: Parameters ---------- should_plot : `bool` Plot the fit if `True`. plot_format : `str`, optional Format of the plot when ``should_plot`` is `True`. We organize Python docstrings into sections that appear in a common order. This format is based on the original Numpydoc Style Guide (used by NumPy, SciPy, and Astropy, among other scientific Python packages), though this style guide includes several DM-specific clarifications.
NumPy
numpy.org › doc › 1.19 › docs › howto_document.html
A Guide to NumPy/SciPy Documentation — NumPy v1.19 Manual
For example, the Yields section was added in numpydoc 0.6. We mostly follow the standard Python style conventions as described here: ... Do not abbreviate scipy. There is no motivating use case to abbreviate it in the real world, so we avoid it in the documentation to avoid confusion. A documentation string (docstring) is a string that describes a module, function, class, or method definition.
DataCamp
datacamp.com › tutorial › docstrings-python
Python Docstrings Tutorial : Examples & Format for Pydoc, Numpy, Sphinx Doc Strings | DataCamp
February 14, 2025 - Learn about Python Docstrings. Find different examples & format types of docstrings for Sphinx, Numpy and Pydoc.
NumPy
numpy.org › doc › 1.20 › docs › howto_document.html
A Guide to NumPy Documentation — NumPy v1.20 Manual
January 31, 2021 - When using Sphinx in combination with the numpy conventions, you should use the numpydoc extension so that your docstrings will be handled correctly. For example, Sphinx will extract the Parameters section from your docstring and convert it into a field list.
GitHub
gist.github.com › 910512d92769b0cc382a09ae4de41771
Very Simple Example of NumPy Style Docstrings · GitHub
Very Simple Example of NumPy Style Docstrings. GitHub Gist: instantly share code, notes, and snippets.
NumPy
numpy.org › doc › 1.21 › docs › howto_document.html
A Guide to NumPy Documentation — NumPy v1.21 Manual
June 22, 2021 - When using Sphinx in combination with the numpy conventions, you should use the numpydoc extension so that your docstrings will be handled correctly. For example, Sphinx will extract the Parameters section from your docstring and convert it into a field list.
Mkdocstrings
mkdocstrings.github.io › python › usage › configuration › docstrings
Docstrings - mkdocstrings-python
::: path.to.module options: docstring_style: numpy · The style is applied to the specified object only, not its members. Local docstring_style options (in ::: instructions) will only be applied to the specified object, and not its members. Instead of changing the style when rendering, we strongly recommend to set the right style as early as possible, for example by using the auto-style (sponsors only), or with a custom Griffe extension ·
GitHub
github.com › numpy › numpydoc › blob › main › doc › example.py
numpydoc/doc/example.py at main · numpy/numpydoc
If your docstring does · extend over multiple lines, the closing three quotation marks must be on · a line by itself, preferably preceded by a blank line. · """ · import os # standard library imports first · · # Do NOT import using *, e.g. from numpy import * # # Import the module using ·
Author: numpy
pyOpenSci
pyopensci.org › python-package-guide › documentation › write-user-documentation › document-your-code-api-docstrings.html
Document the code in your package’s API using docstrings
In the example above, you saw the use of numpy-style docstrings to describe data types that are passed into functions as parameters or into classes as attributes. In a numpy-style docstring you add those types in the Parameters section of the docstring.
NumPy
numpy.org › devdocs › dev › howto-docs.html
How to contribute to the NumPy documentation — NumPy v2.5.dev0 Manual
Some functions/objects like numpy.ndarray.transpose, numpy.array etc. defined in C-extension modules have their docstrings defined separately in _add_newdocs.py
Pyansys
dev.docs.pyansys.com › doc-style › docstrings.html
Numpydoc docstrings — PyAnsys developer's guide
The extended description, which can span multiple lines, should provide a general overview of the function. .. warning:: Use the ``warning`` directive within the docstring for any warnings that need to be explicitly stated. For example, you want to include a warning for a method that is to be deprecated in the next release.
Readthedocs
numpydoc.readthedocs.io › en › v1.0.0 › format.html
numpydoc docstring guide — numpydoc v1.0 Manual
If a method has an equivalent function (which is the case for many ndarray methods for example), the function docstring should contain the detailed documentation, and the method docstring should refer to it. Only put brief summary and See Also sections in the method docstring. The method should use a Returns or Yields section, as appropriate. Instances of classes that are part of the NumPy API (for example np.r_ np.c_, np.index_exp, etc.) may require some care.
pythontutorials
pythontutorials.net › blog › numpy-style-docstrings
Mastering NumPy Style Docstrings: A Comprehensive Guide — pythontutorials.net
For example, if functionA calls functionB, you can mention functionB in the docstring of functionA and provide a link to its documentation if possible. NumPy style docstrings are a powerful tool for documenting Python code, especially in the ...
Top answer 1 of 4
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 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 4
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