docs: one style for docstring section headings, and 1.5.0 for the next release

AGENTS.md

@@ -49,6 +49,12 @@ description and ask first.
   `NDArray` for returned arrays. The shape goes in the docstring (`:type q: array_like(n)`,
   `:rtype: ndarray(6,n)`) where it adds information, not in the annotation. One definition means
   one place to change what "array-like" means.
+- Docstring sections are reST, not NumPy style: a heading is ``.. rubric:: Examples`` (always
+  plural), ``.. rubric:: Notes`` or ``.. rubric:: References``, never an underlined title, and
+  cross-references are ``.. seealso:: :meth:`other```, never ``:seealso:`` (which Sphinx
+  does not know: it renders as one more field after the parameters). A ``.. versionadded::``,
+  ``.. versionchanged::`` or ``.. deprecated::`` names the release it ships in; the next
+  release is the one after the version in ``pyproject.toml``.
 - New code uses modern annotation syntax: `X | Y`, `X | None`, `list[X]`, `dict[K, V]`, not
   `Union`, `Optional`, `List` or `Dict`.
 - Type checking: `mypy` (config in `pyproject.toml`, run it from the repo root with no arguments).

docs/source/IK/analytic.rst

@@ -15,7 +15,7 @@ The same solution can be written out as source code in Python, C, C++ or Rust, f
 
     The ``ik`` extra also installs ``python-flint``, which makes the derivation much faster.  Without it a warning is issued and SymPy is used instead, which gives the same results.  It is not part of the ``all`` extra.
 
-.. versionadded:: 1.6.0
+.. versionadded:: 1.5.0
 
 The notebook `ik-symbolic.ipynb <https://github.com/petercorke/robotics-toolbox-python/blob/main/docs/notebooks/ik-symbolic.ipynb>`_ works through the examples on this page, and more.
 

docs/source/IK/ik.rst

@@ -29,7 +29,7 @@ Member           Meaning
 
 An ``IKSolution`` is a sequence of the rows of ``q``, so ``len(sol)`` is the number of poses and ``for q in sol`` visits them, and ``bool(sol)`` is ``success``.
 
-.. versionchanged:: 1.4.5
+.. versionchanged:: 1.5.0
     Iterating over the six members was removed, use the attributes or ``sol.astuple()``.
 
 The Toolbox has *three ways* to find a solution, shown in the figure.  **Numerical** solvers start from a guess for :math:`\vec{q}` and iterate until the pose is reached.  They work for any robot, and are written in Python, or in C++ for speed.  **Analytic** solvers (see :doc:`analytic`) derive the equations of the inverse kinematics once, symbolically, and then solve them directly for any pose, with no guess and no iteration, giving all the solutions.  They work for six-axis arms, and can write the solution out as source code with no dependency on the Toolbox.

docs/source/IK/numerical.rst

@@ -175,7 +175,7 @@ If ``Tep`` is a trajectory of N poses, each pose is solved independently, starti
 * ``residual`` is the maximum over all poses, the worst case
 * ``reason`` is the reason given by the last pose that failed, if any
 
-.. versionchanged:: 1.4.5
+.. versionchanged:: 1.5.0
     For a trajectory, ``residual`` is the maximum over the poses, it was the minimum.
 
 .. rubric:: The Implemented IK Solvers
@@ -200,7 +200,7 @@ Class               Method                        Notes
     ik_gn
     ik_nr
 
-.. rubric:: Example 
+.. rubric:: Examples
 
 In the following example, we create an IK Solver class and pass an :py:class:`~roboticstoolbox.ets.ETS.ETS` to it to solve the problem. This style may be preferable to experiments where you wish to compare the same solver on different robots.
 
@@ -241,7 +241,7 @@ Additionally, these class-based solvers have been implemented as methods within
     ~roboticstoolbox.robot.Robot.Robot.ikine_NR
 
 
-.. rubric:: Example 
+.. rubric:: Examples
 
 In the following example, we create a :py:class:`~roboticstoolbox.models.URDF.Panda` robot and use one of the IK solvers available within the :py:class:`~roboticstoolbox.robot.Robot.Robot` class. This style is far more convenient than the above example.
 

src/roboticstoolbox/blocks/arm.py

@@ -53,7 +53,7 @@ class FKine(FunctionBlock):
     Compute the end-effector pose as an SE(3) object as a function of the input joint
     configuration.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.fkine`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.fkine`
     """
 
     nin = 1
@@ -124,7 +124,7 @@ class IKine(FunctionBlock):
     :note: The solution may not exist and is not unique.  The solution will depend
         on the initial joint configuration ``q0``.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.ik_LM`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.ik_LM`
     """
 
     nin = 1
@@ -232,7 +232,7 @@ class Jacobian(FunctionBlock):
     Jacobian can be computed in the world or end-effector frame, for spatial or
     analytical velocity, and its inverse, damped inverse or transpose can be returned.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.jacob0`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.jacob0`
         :meth:`~roboticstoolbox.robot.Robot.Robot.jacobe`
         :meth:`~roboticstoolbox.robot.Robot.Robot.jacob0_analytical`
     """
@@ -371,7 +371,7 @@ class ArmPlot(GraphicsBlock):
 
     Create a robot animation using the robot's ``plot`` method.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.plot`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.plot`
     """
 
     nin = 1
@@ -471,7 +471,7 @@ class JTraj(SourceBlock):
     ``qf`` over the course of the simulation. A quintic (5th order) polynomial is used
     with default zero boundary conditions for velocity and acceleration.
 
-    :seealso: :func:`~roboticstoolbox.tools.trajectory.ctraj`
+    .. seealso:: :func:`~roboticstoolbox.tools.trajectory.ctraj`
         ``xplot``
         :func:`~roboticstoolbox.tools.trajectory.jtraj`
     """
@@ -632,7 +632,7 @@ class CTraj(SourceBlock):
     to provide initial acceleration and final deceleration.  Otherwise,
     motion is at constant velocity.
 
-    :seealso: :meth:`~spatialmath.pose3d.SE3.interp`
+    .. seealso:: :meth:`~spatialmath.pose3d.SE3.interp`
         :func:`~roboticstoolbox.tools.trajectory.ctraj`
         ``xplot``
         :func:`~roboticstoolbox.tools.trajectory.jtraj`
@@ -825,7 +825,7 @@ class Trapezoidal(SourceBlock):
         element, because ``trapezoidal_func`` returned arrays for a scalar
         time.
 
-    :seealso: ``ctraj``, ``xplot``, :func:`~roboticstoolbox.tools.trajectory.jtraj`
+    .. seealso:: ``ctraj``, ``xplot``, :func:`~roboticstoolbox.tools.trajectory.jtraj`
     """
 
     nin = 0
@@ -916,7 +916,7 @@ class Traj(FunctionBlock):
         previously failed with an ``UnboundLocalError`` when the simulation
         started.  The outputs are unchanged.
 
-    :seealso: :func:`spatialmath.base.mtraj`
+    .. seealso:: :func:`spatialmath.base.mtraj`
     """
 
     nin = -1
@@ -1064,7 +1064,7 @@ class IDyn(FunctionBlock):
 
     .. todo:: end-effector wrench input, base wrench output, payload input
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.rne`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.rne`
     """
 
     nin = 3
@@ -1134,7 +1134,7 @@ class Gravload(FunctionBlock):
     Compute generalized joint forces due to gravity for the input joint
     configuration.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.gravload`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.gravload`
     """
 
     nin = 1
@@ -1197,7 +1197,7 @@ class Gravload_X(FunctionBlock):
 
     Compute end-effector wrench due to gravity for the input end-effector pose.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.gravload_x`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.gravload_x`
         :meth:`~roboticstoolbox.robot.Robot.Robot.gravload`
     """
 
@@ -1280,7 +1280,7 @@ class Inertia(FunctionBlock):
 
     Joint-space inertia matrix (mass matrix) as a function of joint configuration.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.inertia`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.inertia`
     """
 
     nin = 1
@@ -1342,7 +1342,7 @@ class Inertia_X(FunctionBlock):
 
     Task-space inertia matrix as a function of end-effector pose.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.inertia_x`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.inertia_x`
     """
 
     nin = 1
@@ -1424,7 +1424,7 @@ class FDyn(ContinuousBlock):
     for the input configuration and applied joint forces.  The acceleration is
     integrated to obtain joint velocity and joint configuration.
 
-    :seealso: :meth:`~roboticstoolbox.robot.Robot.Robot.fdyn`
+    .. seealso:: :meth:`~roboticstoolbox.robot.Robot.Robot.fdyn`
     """
 
     nin = 1
@@ -1523,7 +1523,7 @@ class FDyn_X(ContinuousBlock):
     acceleration for the input end-effector pose and applied end-effector wrench.  The
     acceleration is integrated to obtain task-space velocity and task-space pose.
 
-    :seealso: ``fdyn_x``
+    .. seealso:: ``fdyn_x``
     """
 
     nin = 1

src/roboticstoolbox/blocks/mobile.py

@@ -59,7 +59,7 @@ class Bicycle(ContinuousBlock):
     * acceleration limit ``accel_max``
     * steering limit ``steer_max``
 
-    :seealso: :class:`~roboticstoolbox.mobile.Vehicle.Bicycle` :class:`Unicycle` :class:`DiffSteer`
+    .. seealso:: :class:`~roboticstoolbox.mobile.Vehicle.Bicycle` :class:`Unicycle` :class:`DiffSteer`
     """
 
     nin = 2
@@ -173,7 +173,7 @@ class Unicycle(ContinuousBlock):
     * acceleration limit ``accel_max``
     * steering limit ``steer_max``
 
-    :seealso: :class:`~roboticstoolbox.mobile.Vehicle.Unicycle` :class:`Bicycle` :class:`DiffSteer`
+    .. seealso:: :class:`~roboticstoolbox.mobile.Vehicle.Unicycle` :class:`Bicycle` :class:`DiffSteer`
 
     """
 
@@ -278,7 +278,7 @@ class DiffSteer(ContinuousBlock):
     .. note:: Wheel velocity is defined such that if both are positive the vehicle
             moves forward.
 
-    :seealso: :class:`~roboticstoolbox.mobile.Vehicle.DiffSteer` :class:`Bicycle` :class:`Unicycle`
+    .. seealso:: :class:`~roboticstoolbox.mobile.Vehicle.DiffSteer` :class:`Bicycle` :class:`Unicycle`
     """
 
     nin = 2
@@ -407,7 +407,7 @@ def __init__(
         :param blockargs: |GraphicsBlockOptions|
         :raises TypeError: ``animation`` is not a ``VehicleAnimationBase``
 
-        .. deprecated:: 1.4.5
+        .. deprecated:: 1.5.0
             the arguments ``path``, ``init``, ``scale`` and ``polyargs`` are
             deprecated, use ``path_style``, ``init_func``, ``limits`` and
             ``polygon_style`` instead.

src/roboticstoolbox/blocks/spatial.py

@@ -40,7 +40,7 @@ class Tr2Delta(FunctionBlock):
 
     Difference between :math:`\mathbf{T}_1` and :math:`\mathbf{T}_2` as a 6-vector
 
-    :seealso: :class:`Delta2Tr` :func:`~spatialmath.base.transforms3d.tr2delta`
+    .. seealso:: :class:`Delta2Tr` :func:`~spatialmath.base.transforms3d.tr2delta`
     """
 
     nin = 2
@@ -93,7 +93,7 @@ class Delta2Tr(FunctionBlock):
 
     6-vector spatial displacement to transform.
 
-    :seealso: :class:`Tr2Delta` :func:`~spatialmath.base.transforms3d.delta2tr`
+    .. seealso:: :class:`Tr2Delta` :func:`~spatialmath.base.transforms3d.delta2tr`
     """
 
     nin = 1
@@ -209,7 +209,7 @@ class TR2T(FunctionBlock):
             - float
             - :math:`z` component of translation.
 
-    :seealso: :func:`~spatialmath.base.transforms3d.transl`
+    .. seealso:: :func:`~spatialmath.base.transforms3d.transl`
     """
 
     nin = 1

src/roboticstoolbox/blocks/uav.py

@@ -95,7 +95,7 @@ class MultiRotor(ContinuousBlock):
           Australian National University, 2007.
         - Robotics, Vision & Control by Peter Corke, sec 4.2 in all editions
 
-    :seealso: :class:`MultiRotorMixer` :class:`MultiRotorPlot`
+    .. seealso:: :class:`MultiRotorMixer` :class:`MultiRotorPlot`
     """
 
     nin = 1
@@ -517,7 +517,7 @@ class MultiRotorMixer(FunctionBlock):
 
     .. note:: Based on MATLAB code developed by Pauline Pounds 2004.
 
-    :seealso: :class:`MultiRotor` :class:`MultiRotorPlot`
+    .. seealso:: :class:`MultiRotor` :class:`MultiRotorPlot`
     """
 
     nin = 4
@@ -638,7 +638,7 @@ class MultiRotorPlot(GraphicsBlock):
 
     .. note:: Based on MATLAB code developed by Pauline Pounds 2004.
 
-    :seealso: :class:`MultiRotor` :class:`MultiRotorMixer`
+    .. seealso:: :class:`MultiRotor` :class:`MultiRotorMixer`
     """
 
     nin = 1

src/roboticstoolbox/ets/ET.py

@@ -140,8 +140,7 @@ def A(self, q: float | Sym = 0.0) -> ndarray:
         :returns: The SE(3) matrix value of the ET
         :rtype: ndarray
 
-        Examples
-        --------
+        .. rubric:: Examples
 
         .. runblock:: pycon
 
@@ -209,10 +208,7 @@ def Rx(
           angle, i.e. a revolute robot joint. ``j`` or ``flip`` can be set in
           this case.
 
-        See Also
-        --------
-        :func:`ET`
-        :func:`isrotation`
+        .. seealso:: :func:`ET` :func:`isrotation`
 
         :SymPy: supported
         """
@@ -244,10 +240,7 @@ def Ry(
           angle, i.e. a revolute robot joint. ``j`` or ``flip`` can be set in
           this case.
 
-        See Also
-        --------
-        :func:`ET`
-        :func:`isrotation`
+        .. seealso:: :func:`ET` :func:`isrotation`
 
         :SymPy: supported
         """
@@ -279,10 +272,7 @@ def Rz(
           angle, i.e. a revolute robot joint. ``j`` or ``flip`` can be set in
           this case.
 
-        See Also
-        --------
-        :func:`ET`
-        :func:`isrotation`
+        .. seealso:: :func:`ET` :func:`isrotation`
 
         :SymPy: supported
         """
@@ -312,10 +302,7 @@ def tx(
           variable distance, i.e. a prismatic robot joint. ``j`` or ``flip``
           can be set in this case.
 
-        See Also
-        --------
-        :func:`ET`
-        :func:`istranslation`
+        .. seealso:: :func:`ET` :func:`istranslation`
 
         :SymPy: supported
         """
@@ -357,10 +344,7 @@ def ty(
           variable distance, i.e. a prismatic robot joint. ``j`` or ``flip``
           can be set in this case.
 
-        See Also
-        --------
-        :func:`ET`
-        :func:`istranslation`
+        .. seealso:: :func:`ET` :func:`istranslation`
 
         :SymPy: supported
         """
@@ -401,10 +385,7 @@ def tz(
           variable distance, i.e. a prismatic robot joint. ``j`` or ``flip``
           can be set in this case.
 
-        See Also
-        --------
-        :func:`ET`
-        :func:`istranslation`
+        .. seealso:: :func:`ET` :func:`istranslation`
 
         :SymPy: supported
         """
@@ -431,10 +412,7 @@ def SE3(cls, T: ndarray | SE3T, **kwargs: Any) -> ET:
         :returns: An elementary transform
         :rtype: ET
 
-        See Also
-        --------
-        :func:`ET`
-        :func:`istranslation`
+        .. seealso:: :func:`ET` :func:`istranslation`
 
         :SymPy: supported
         """