Documentation Style Gudie

Documentation Style Guide

Use the numpy docstring style. See examples here

Example NumPy Style Python Docstrings - napoleon 0.7 documentation

Any directive given in this document super-seeds those given in the style guide above. Our priority is to have both excellent generated documentation using Sphinx and readable tooltip docstrings.

Style Guide

1. Docstrings

Docstring Section Ordering

"""
One line description

Longer paragraph description. Each section of the docstring should
be seperated by a single line, except for rst directives (lines
that start with ".. " which should be seperated by 2 blank lines

Note
----
An optional emphasised important single note

Attributes
----------
hermitian
   If True, `a` is a ...

Raises
------
LinAlgError
    If the SVD computation does not converge.

Returns
-------
b
    The pseudo-inverse of ...

Synopsis
--------
Here is an extended description...

Examples
--------
Example description

.. runblock:: pycon
>>> import roboticstoolbox as rtb
>>> panda = rtb.models.Panda().ets()
>>> solver = rtb.IK_QP()
>>> Tep = panda.fkine([0, -0.3, 0, -2.2, 0, 2, 0.7854])
>>> solver.solve(panda, Tep)

Notes
-----
- Lower priority notes
- The pseudo-inverse of a matrix A, ...
- Another note 

References
----------
.. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando,
       FL, Academic Press, Inc., 1980, pp. 139-142.

See Also
--------
scipy.linalg.pinv : Similar function in SciPy.

.. versionchanged:: X.Y.Z
    Description of change

"""

Class Docstrings

Class docstrings should be immediately below the class declaration and __init__ methods should not have a docstring. See example:

class ExampleClass():
    """
    The summary line for a class docstring should fit on one line.

    Parameters
    ----------
    param1
        Description of `param1`.
    param2
        Description of `param2`. Multiple
        lines are supported.
    param3
        Description of `param3`.

    """

    def __init__(self, param1, param2, param3):
				"""
        Not here, there should be NO docstring here
        """
				pass

Setters and Properties

@property
def name(self):
    """
    Set/get image name

    An image has a string-valued name that can be read and written.
    The name is shown by the Image repr and when images are displayed
    graphically.

    Example
    -------
    Example description

    .. runblock:: pycon
    >>> from machinevisiontoolbox import Image
    >>> img = Image.Read('flowers1.png')
    >>> img.name[-70:]
    >>> img.name = 'my image'
    >>> img.name

    Notes
    -----
    Images loaded from a file have their name initially set to
    the full file pathname.
    
    See Also
    --------
    :meth:`Read`
    """
  return self._name

@name.setter
def name(self, name):
    self._name = name

References

"""
Use numbered references with the directive if you refer to the reference.
Otherwise use a bullet point.

References
----------
.. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando,
       FL, Academic Press, Inc., 1980, pp. 139-142.
.. [2] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando,
       FL, Academic Press, Inc., 1980, pp. 139-142.

OR

References
----------
- G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando,
  FL, Academic Press, Inc., 1980, pp. 139-142.
- G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando,
  FL, Academic Press, Inc., 1980, pp. 139-142.

"""

Code Examples

Code examples should start with .. runblock:: pycon and the the example proceeding on the next line WITHOUT a blank line or an indent

"""
Examples
--------
Example description

.. runblock:: pycon
>>> import roboticstoolbox as rtb
>>> panda = rtb.models.Panda().ets()
>>> solver = rtb.IK_QP()
>>> Tep = panda.fkine([0, -0.3, 0, -2.2, 0, 2, 0.7854])
>>> solver.solve(panda, Tep)

"""

2. Restructured Text for Built Docs

Class rst

A typical class level rst file will look like

ClassName - Short Description (Optional)
----------------------------------------

.. currentmodule:: roboticstoolbox.robot.IK

.. autoclass:: ClassName
   :show-inheritance:

.. rubric:: Methods

.. autosummary::
   :toctree: stubs

   ~ClassName.meth1
   ~ClassName.meth2
   ~ClassName.meth3

.. rubric:: Private Methods (Optional)

.. autosummary::
   :toctree: stubs
   
   ~ClassName._pmeth1
   ~ClassName._pmeth2

Note how there is no entry for __init__ as that is documented with the autoclass directive.

Miscellaneous

Current Module

Use .. currentmodule:: roboticstoolbox.robot.IK to shorten future references within that module. With that directive I can now use IK_NR and/or IK_NR.step instead of roboticstoolbox.robot.IK.IK_NR.step. This will also shorten what is rendered.

**The ~**

Use a ~ to shorten a reference to the last section in what is rendered. For example ~IK.IK_NR.step is rendered as step in the resulting HTML files.