Attributes ---------- module_level_variable1 : int Module level variables may be documented in either the ``Attributes`` section of the module docstring, or in an inline docstring immediately following the variable. Either form is acceptable, but the two should not be mixed. Choose one convention to document module level variables and be consistent with it. .. _NumPy Documentation HOWTO: https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt """ module_level_variable1 = 12345 module_level_variable2 = 98765 """int: Module level variable documented inline.

Support for the Yields section was added in numpydoc version 0.6. Explanation of parameters passed to a generator’s .send() method, formatted as for Parameters, above. Since, like for Yields and Returns, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple. If a docstring includes Receives it must also include Yields.

""" msg = None """Human readable string describing the exception (`str`). """ code = None """Numeric error code (`int`). """ def __init__(self, msg, code=None): self.msg = msg self.code = code · These docstring guidelines are derived/adapted from the Numpydoc and Astropy documentation.

Attributes ---------- module_level_variable1 : int Module level variables may be documented in either the ``Attributes`` section of the module docstring, or in an inline docstring immediately following the variable. Either form is acceptable, but the two should not be mixed. Choose one convention to document module level variables and be consistent with it. .. _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.

Using numpydoc will also avoid the reStructuredText errors produced by plain Sphinx when it encounters NumPy docstring conventions like section headers (e.g. -------------) that sphinx does not expect to find in docstrings. ... Note that for documentation within NumPy, it is not necessary to do import numpy as np at the beginning of an example. Please use the numpydoc formatting standard as shown in their example. NumPy uses Doxygen to parse specially-formatted C/C++ comment blocks.

Using numpydoc will also avoid ... find in docstrings. ... Note that for documentation within NumPy, it is not necessary to do import numpy as np at the beginning of an example. Please use the numpydoc formatting standard as shown in their example. NumPy uses Doxygen to parse specially-formatted C/C++ comment blocks...

If t (the default) a Raises bock will be added to the docstring if exceptions are detected in the function body. ... If t a Returns block will be inserted in the absence of a return type hint. ... Template text that will be used as the short description if numpydoc-insertion-style is nil.

Calling numpydoc-generate parses a function signature and body (corresponding to the current cursor location; just have the cursor somewhere in the function you want to document) detecting argument names, type hints, exceptions, and the return type hint. This information is used to generate a 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.

It was designed to be compared ... header docstring above. import numpy as np # noqa: F401 # %% # You can separate code blocks using either a single line of ``#``'s # (>=20 columns), ``#%%``, or ``# %%``. For consistency, it is recommend that # you use only one of the above ...

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.

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

Use *italics*, **bold** and ``monospace`` if needed in any explanations (but not for variable names and doctest code or multi-line code). Variable, module, function, and class names should be written between single back-ticks (`numpy`). A more extensive example of reST markup can be found in this example document; the quick reference is useful while editing. Line spacing and indentation are significant and should be carefully followed. This document itself was written in ReStructuredText. An example of the format shown here is available. """This is the docstring for the example.py module.

Support for the Yields section was added in numpydoc version 0.6. ... Explanation of parameters passed to a generator’s .send() method, formatted as for Parameters, above. Since, like for Yields and Returns, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple. If a docstring includes Receives it must also include Yields.

In rare occasions reST styles like bold text or itallics will be used in docstrings, but is it common to have inline code, which is presented between backticks. It is considered inline code: ... Python code, a module, function, built-in, type, literal… (e.g. os, list, numpy.abs, datetime.date, True)

Surrounding text in a single backtick in a PyAnsys library formats it in italic type rather than as a code entity. PyAnsys library docstrings contain these numpydoc sections as a minimum:

October 4, 2023 - Describe the bug For a function with a docstring like this: def f(): """ one liner, this isn't shown longer description, this isn't shown See Also -------- [related function, this is shown](#related_function) """ griffe's numpydoc parses...

A Numpy-style docstrings parser. Source code in src/pytkdocs/parsers/docstrings/numpy.py

October 11, 2020 - """ msg = None """Human readable string describing the exception (`str`). """ code = None """Numeric error code (`int`). """ def __init__(self, msg, code=None): self.msg = msg self.code = code · These docstring guidelines are derived/adapted from the NumPy and Astropy documentation.

VSCode extension that generates docstrings for python files - autoDocstring/docs/numpy.md at c9da64126fd9e667decd9d85b4e5b53c60372ea7 · NilsJPWerner/autoDocstring