You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Looks like we need a consistent docstring format. Even just in molevol.py there are quite a few variations. I'll suggest the following for detailed doc strings (mostly inspired by the linked comment):
"""
Short one-line description of function or method.
Additional general detail if desired
Args:
argument1 (type): Description
argument2 (type): Long description may take up
multiple lines, with a single additional indent level (four spaces) denoting subsequent lines after the first
Returns:
return_type: Description, with indenting rules from above.
"""
A few other suggested details (following how e.g. gctree formats doc strings)
Class doc strings may have an additional Attributes: header describing public attributes. Constructor documentation, including Args: should be provided in the class-level docstring.
Additional headers like Notes: and Examples: can appear after Returns:.
Questions:
If we're going to use Sphinx autodoc like gctree does, we should consider omitting the (type) annotations on arguments and return values, because autodoc gets those from type annotations, and automatically links them to the relevant documentation for that type.
Also a sphinx thing, inline code requires double back quotes like ``inline code``.
However, any inline mention of a method, function, or class should be formatted like: :meth:`name`, :func:`name`, or :class:`name`
so that autodoc will insert the link to the corresponding documentation. Do we want to use these here?
In gctree, all public functions are required to have a docstring, and private functions (e.g. beginning with underscore) have a docstring only when it seems helpful. Keep that policy here?
Looks like we need a consistent docstring format. Even just in
molevol.py
there are quite a few variations. I'll suggest the following for detailed doc strings (mostly inspired by the linked comment):A few other suggested details (following how e.g.
gctree
formats doc strings)Attributes:
header describing public attributes. Constructor documentation, includingArgs:
should be provided in the class-level docstring.Notes:
andExamples:
can appear afterReturns:
.Questions:
gctree
does, we should consider omitting the(type)
annotations on arguments and return values, because autodoc gets those from type annotations, and automatically links them to the relevant documentation for that type.``inline code``
.However, any inline mention of a method, function, or class should be formatted like:
:meth:`name`, :func:`name`, or :class:`name`
so that autodoc will insert the link to the corresponding documentation. Do we want to use these here?
Inspired by the comment from @matsen in #50 (comment)
The text was updated successfully, but these errors were encountered: