Skip to content

Documentation Style Guide

Jump to bottom
Jesse Haviland edited this page Dec 24, 2022 · 2 revisions

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.

General

Robot arms

Development (current)

OLD

Early design ideas

Clone this wiki locally