.. _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....

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.

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]#

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.

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

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.

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.

.. _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.

February 14, 2025 - Learn about Python Docstrings. Find different examples & format types of docstrings for Sphinx, Numpy and Pydoc.

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.

Very Simple Example of NumPy Style Docstrings. GitHub Gist: instantly share code, notes, and snippets.

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.

Some functions/objects like numpy.ndarray.transpose, numpy.array etc. defined in C-extension modules have their docstrings defined separately in _add_newdocs.py

::: 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 ·

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.

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 ·

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.

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.

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

May 25, 2022 - As so often in the Python world, there are a few best practices on how to do something, in this case how to write docstrings properly. Three main styles have evolved: the traditional style, the Google style, and the NumPy style. I advocate the NumPy style because it is very human-readable (in ...