: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
"""
#### epytext
- This is the default in epydoc (see below)
- Supported in Pycharm
"""
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
"""
#### Google
"""
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.
"""
#### [Numpydoc](https://numpydoc.readthedocs.io/en/latest/)
- Used by numpy
- Supported in Pycharm
"""
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
"""
### Docstring-to-doc generators
- [Sphinx](https://www.sphinx-doc.org/en/master/)
- [MkDocs](https://www.mkdocs.org)
- [epydoc](https://pypi.org/project/epydoc/)
- Make sure it's supported by [ReadTheDocs.io](http://readthedocs.io)
## History
We should also maybe settle on a fixed docstring format, because then we can use tooling to automatically create browseable API documentation.
_Originally posted by @caiw in https://github.com/kymata-atlas/kymata-toolbox/issues/186#issuecomment-1961212272_
caiw
commented
3 months ago
Options
Formats
(A lot of this copied from SO: What are the most common Python docstring formats?)
ReStructuredText
: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 """
""" 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 """
""" 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. """
""" My numpydoc description of a kind of very exhautive numpydoc format docstring.
Parameters
first : array_like the 1st param name
firstsecond : 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 """