Documentation Style Guide

Documentation Style Guide

RTB uses reST-style docstrings rendered with Sphinx, not the NumPy docstring style. This convention is shared across Peter's Python toolboxes (RTB, MVTB, SMTB, bdsim); see the rvc-ecosystem repo's AGENTS.md (§5, Code Standards) for the canonical source.

Style Guide

1. Docstrings

• reST style: :param name:, :returns: — not NumPy-style section headers (Parameters/Returns/Notes underlined with dashes)
• Every docstring has a one-line summary, followed by a :param:/:returns: block, followed by extended description and notes
• Where appropriate, a docstring ends with :seealso: cross-links as its last line
• Docstring references to classes and methods use the :meth: and :class: roles, not plain text or Markdown-style backticks
• :type: / :rtype: are used only when shape information adds value beyond the signature's type hint (e.g. :type q: ndarray(6,n)) — the type hint itself covers everything else, so don't restate a plain type in :type:/:rtype: as a matter of habit
• Math docstrings use r"""...""" (a raw string) so LaTeX in :math: renders correctly
• All public methods and functions are type-hinted, using modern syntax: X | Y, X | None, list[X], dict[K, V] — not Union, Optional, List, Dict from typing

Docstring Section Ordering

r"""
One line description.

Longer paragraph description. Each section of the docstring should be
separated by a blank line.

:param name: description of the parameter
:type name: ndarray(6,n)
:param other: description of another parameter
:return: description of the return value

.. note::
    An optional emphasised important note.

.. warning::
    An optional warning about a gotcha or unsafe usage.

Extended discussion, background, or a worked mathematical explanation can go
here, after the parameter/return block.

Example::

    Prose describing what the example below shows.

.. 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)

.. seealso:: :meth:`related_method`, :class:`RelatedClass`
"""

Real example, from roboticstoolbox/robot/IK.py's IK_NR class:

class IK_NR(IKSolver):
    r"""
    Newton-Raphson Numerical Inverse Kinematics Solver

    A class which provides functionality to perform numerical inverse
    kinematics (IK) using the Newton-Raphson method. See `step` method for
    mathematical description.

    .. note::

        When using this class with redundant robots (>6 DoF), `pinv` must
        be set to `True`

    :param name: The name of the IK algorithm
    :param ilimit: How many iterations are allowed within a search before
        a new search is started
    :param tol: Maximum allowed residual error E, where
        :math:`E = \tfrac{1}{2} \vec{e}^\top \mat{W}_e \vec{e}` ...
    """

Class Docstrings

The class docstring documents the constructor's parameters (via :param:), and lives immediately below the class declaration. __init__ itself does not get its own docstring — see IK_NR above: the docstring is on class IK_NR(IKSolver):, and def __init__(self, name=..., ilimit=..., ...): has none.

Code Examples

Code examples that should actually execute (and show real, current output) use .. runblock:: pycon, with the example starting on the next line, no blank line and no indent:

.. 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)

If the example would produce huge or non-deterministic output (hundreds of table rows, a randomly-seeded result, anything that opens a window or a network connection — e.g. Swift's browser-based visualizer), use a plain, static .. code-block:: pycon (or .. code-block:: text for output) instead, with hand-written representative output. Don't runblock something whose real captured output would be misleading or broken in the built HTML — see docs/source/intro.rst's catalog() example and its Swift-plot example for both cases in practice.

2. Restructured Text for Built Docs

Class/module reference pages use plain automodule/autoclass directives.

A page documenting a whole module (several related classes), e.g. arm_superclass.rst:

.. automodule:: roboticstoolbox.robot.Robot
   :members:
   :undoc-members:
   :show-inheritance:
   :inherited-members:
   :special-members: __getitem__

A page documenting a single class, e.g. mobile-vehicle-bicycle.rst:

.. autoclass:: roboticstoolbox.mobile.Bicycle
   :members:
   :undoc-members:
   :show-inheritance:
   :inherited-members:
   :special-members: __init__

:special-members: is only needed to pull in a dunder method (like __init__ or __getitem__) that Sphinx doesn't document by default.