fix(docs): resolve reST syntax and structural Sphinx build warnings

docs/source/_templates/autosummary/method.rst

@@ -1,7 +1,8 @@
 :orphan:
 
-{{ class + '.' + name | escape | underline}}
+{{ (class + '.' + name) | escape | underline}}
 
 .. currentmodule:: {{ module }}
 
 .. auto{{ objtype }}:: {{ fullname }}
+   :no-index:

docs/source/conf.py

@@ -170,7 +170,14 @@
 # the documentation
 napoleon_include_special_with_doc = True
 
-napoleon_custom_sections = ["Synopsis"]
+# Napoleon is still needed: tools/urdf/utils.py and urdf.py have genuine
+# NumPy-style docstrings (vendored/adapted from an external URDF library)
+# that depend on it. Everywhere else uses explicit reST fields directly.
+# Bare NumPy-style section headers (Note, Examples, See Also, ...) mixed
+# into otherwise-reST docstrings should use explicit directives
+# (.. rubric:: Notes, etc.) instead — Napoleon's heuristic recognition of
+# those bare headers can conflict with sphinx_autodoc_typehints (see
+# tech-debt.md, 2026-07-05).
 
 # -------- Options AutoSummary -------------------------------------------------------#
 
@@ -187,11 +194,18 @@
 # -------- Suppress common noisy warnings ----------------------------------------#
 
 # Suppress "more than one target found" for short/common attribute names like
-# n, m, robot, symbolic that appear across many classes, and suppress duplicate
-# object description warnings for classes documented both inline and in stubs.
+# n, m, robot, symbolic that appear across many classes, and duplicate-citation
+# warnings for references (e.g. Yoshikawa85) defined in both a narrative page
+# and a docstring pulled in from two classes.
+#
+# Note: "duplicate object description" (autodoc members documented both
+# inline and via a separate IK/stubs/ page) is a different warning class
+# with no type/subtype tag at all, so it can't be suppressed here — it's
+# fixed at the source instead, via :no-index: in
+# _templates/autosummary/method.rst.
 suppress_warnings = [
     "ref.python",  # ambiguous cross-references (multiple targets for 'n', 'm', etc.)
-    "duplicate",  # duplicate object descriptions (IKSolution, IKSolver defined twice)
+    "ref.citation",  # duplicate citations (Yoshikawa85 etc in both arm_*.rst and docstrings)
 ]
 
 # -------- Options favicon -------------------------------------------------------#

src/roboticstoolbox/blocks/arm.py

@@ -366,7 +366,6 @@ class ArmPlot(GraphicsBlock):
             - 0
             - ndarray(N)
             - :math:`\mathit{q}`, joint configuration
-        *   - Output
 
     Create a robot animation using the robot's ``plot`` method.
 

src/roboticstoolbox/models/DH/Hyper.py

@@ -38,8 +38,8 @@ class Hyper(DHRobot):
     :References:
 
       - "A divide and conquer articulated-body algorithm for parallel O(log(n))
-      calculation of rigid body dynamics, Part 2",
-      Int. J. Robotics Research, 18(9), pp 876-892.
+        calculation of rigid body dynamics, Part 2",
+        Int. J. Robotics Research, 18(9), pp 876-892.
 
     :seealso: :func:`Coil`, :func:`Ball`
 

src/roboticstoolbox/models/DH/Hyper3d.py

@@ -38,8 +38,8 @@ class Hyper3d(DHRobot):
     :References:
 
       - "A divide and conquer articulated-body algorithm for parallel O(log(n))
-      calculation of rigid body dynamics, Part 2",
-      Int. J. Robotics Research, 18(9), pp 876-892.
+        calculation of rigid body dynamics, Part 2",
+        Int. J. Robotics Research, 18(9), pp 876-892.
 
     :seealso: :func:`Coil`, :func:`Ball`
 

src/roboticstoolbox/models/DH/Orion5.py

@@ -34,8 +34,8 @@ class Orion5(DHRobot):
       - Robot has only 4 DoF.
 
     :references:
-        - https://rawrobotics.com.au/orion5
-        - https://drive.google.com/file/d/0B6_9_-ZgiRdTNkVqMEkxN2RSc2c/view
+        - ``https://rawrobotics.com.au/orion5``
+        - ``https://drive.google.com/file/d/0B6_9_-ZgiRdTNkVqMEkxN2RSc2c/view``
 
     .. codeauthor:: Aditya Dua
     .. codeauthor:: Peter Corke

src/roboticstoolbox/models/ETS/Puma560.py

@@ -15,10 +15,11 @@ class Puma560(Robot):
 
         - The model has different joint offset conventions compared to
           ``DH.Puma560()``. For this robot:
-            - Zero joint angles ``qz`` is the vertical configuration,
-              corresponding to ``qr`` with ``DH.Puma560()``
-            - ``qbent`` is the bent configuration, corresponding to
-              ``qz`` with ``DH.Puma560()``
+
+          - Zero joint angles ``qz`` is the vertical configuration,
+            corresponding to ``qr`` with ``DH.Puma560()``
+          - ``qbent`` is the bent configuration, corresponding to
+            ``qz`` with ``DH.Puma560()``
 
     :references:
         - "A Simple and Systematic Approach to Assigning Denavit–Hartenberg