From eb9da0b567d3328573027f86de343a7b55f5d2e1 Mon Sep 17 00:00:00 2001
From: Tobias Fischer <info@tobiasfischer.info>
Date: Thu, 27 Aug 2026 16:02:19 +1000
Subject: [PATCH] docs: showcase trchain runblock examples

---
 docs/source/arm_ets.rst | 51 ++++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/docs/source/arm_ets.rst b/docs/source/arm_ets.rst
index 1521b416e..6f1c7ee23 100644
--- a/docs/source/arm_ets.rst
+++ b/docs/source/arm_ets.rst
@@ -72,18 +72,63 @@ Transform chains
 The :func:`~roboticstoolbox.tools.trchain.trchain` and
 :func:`~roboticstoolbox.tools.trchain.trchain2` functions provide the compact
 string notation used by the MATLAB Toolbox for one-off SE(3) and SE(2)
-transform chains.  Joint variables are numbered from one, while named
+transform chains.
+
+Three-dimensional chains contain rotations and translations about or along
+any Cartesian axis.  Joint variables are numbered from one, and named
 constants are passed explicitly in ``variables``.
 
 .. runblock:: pycon
 
    >>> import roboticstoolbox as rtb
-   >>> rtb.trchain("Rz(q1) Tx(a)", [0.3], variables={"a": 1})
-   >>> rtb.trchain2("R(q1) Tx(a)", [0.3], variables={"a": 1})
+   >>> q = [0.2, -0.3, 0.4]
+   >>> rtb.trchain("Rx(q1) Ry(q2) Rz(q3) Tx(x) Ty(y) Tz(z)", q,
+   ...             variables={"x": 0.5, "y": 0.2, "z": 0.1})
+
+Arguments can use arithmetic, the names ``pi``, ``sin``, ``cos``, ``tan`` and
+``sqrt``, or functions supplied in ``variables``.  The joint prefix and angle
+unit can also be changed.
+
+.. runblock:: pycon
+
+   >>> import roboticstoolbox as rtb
+   >>> rtb.trchain("Rz(pi / 2) Tx(sqrt(4)) Ty(sin(pi / 2) + cos(0) + tan(0))")
+   >>> double = lambda value: 2 * value
+   >>> rtb.trchain("Rz(theta1 - 45) Tx(double(a))", [90], unit="deg",
+   ...             qvar="theta", variables={"a": 0.5, "double": double})
+
+For planar motion, :func:`~roboticstoolbox.tools.trchain.trchain2` accepts
+``R`` (or ``Rz``), ``Tx`` and ``Ty`` transforms.
+
+.. runblock:: pycon
+
+   >>> import numpy as np
+   >>> import roboticstoolbox as rtb
+   >>> rtb.trchain2("R(q1) Tx(L1) Rz(q2) Tx(L2) Ty(y)",
+   ...              [np.pi / 2, -np.pi / 2],
+   ...              variables={"L1": 1, "L2": 0.5, "y": 0.25})
 
 Parsed tokens can also be returned and reused when evaluating the same chain
 for different joint values.
 
+.. runblock:: pycon
+
+   >>> import roboticstoolbox as rtb
+   >>> _, tokens = rtb.trchain("Rz(q1) Tx(a)", [0], variables={"a": 1},
+   ...                         return_tokens=True)
+   >>> tokens
+   >>> rtb.trchain(tokens, [0.5], variables={"a": 1})
+
+Joint values and named constants can be symbolic.
+
+.. runblock:: pycon
+
+   >>> import roboticstoolbox as rtb
+   >>> import sympy
+   >>> q, a = sympy.symbols("q a", real=True)
+   >>> T = rtb.trchain("Rz(q1) Tx(a)", [q], variables={"a": a})
+   >>> T[0, 0], T[0, 3], T[1, 3]
+
 .. autofunction:: roboticstoolbox.tools.trchain.trchain
 
 .. autofunction:: roboticstoolbox.tools.trchain.trchain2