Skip to content

Commit fff7009

Browse files
docs: fix Sphinx docstring formatting and reST syntax errors (#195)
Co-authored-by: Jenny Barry <116907872+jbarry-bdai@users.noreply.github.com>
1 parent cb1ecc1 commit fff7009

18 files changed

Lines changed: 149 additions & 144 deletions

‎docs/source/classes-2d.rst‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎docs/source/classes-3d.rst‎

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎docs/source/intro.rst‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,7 @@ The classes ``SE3``, ``SO3``, ``SE2`` and ``SO2`` can provide colorized text out
262262

263263
.. image:: ../figs/colored_output.png
264264
:width: 300
265+
265266
with rotational elements in red, translational elements in blue and constants in grey.
266267

267268
The foreground and background colors can be controlled using the following
@@ -538,8 +539,10 @@ A numpy column vector has shape ``(N,1)`` and a row vector
538539
has shape ``(1,N)`` but functions also accept row ``(1,N)`` and column ``(N,1)``
539540
where a vector argument is required.
540541

541-
.. warning:: For a user transitioning from MATLAB the most significant
542-
differences are:
542+
.. warning::
543+
544+
For a user transitioning from MATLAB the most significant differences are:
545+
543546
- the use of 1D arrays -- all MATLAB arrays have two dimensions,
544547
even if one of them is equal to one.
545548
- Iterating over a 1D NumPy array (N,) returns consecutive elements

‎spatialmath/DualQuaternion.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -338,7 +338,7 @@ def SE3(self) -> SE3:
338338
339339
.. runblock:: pycon
340340
341-
>>> from spatialmath import DualQuaternion, SE3
341+
>>> from spatialmath import UnitDualQuaternion, SE3
342342
>>> T = SE3.Rand()
343343
>>> print(T)
344344
>>> d = UnitDualQuaternion(T)

‎spatialmath/base/argcheck.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,7 @@ def isinteger(x: Any) -> bool:
6262
6363
.. runblock:: pycon
6464
65-
>>> from spatialmath.base import isscalar
65+
>>> from spatialmath.base import isinteger
6666
>>> isinteger(1)
6767
>>> isinteger(1.2)
6868

‎spatialmath/base/graphics.py‎

Lines changed: 20 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -115,42 +115,41 @@ def plot_point(
115115
Plot one or more points, with optional text label.
116116
117117
- The color of the marker can be different to the color of the text, the
118-
marker color is specified by a single letter in the marker string.
118+
marker color is specified by a single letter in the marker string.
119119
120120
- A point can have multiple markers, given as a list, which will be
121-
overlaid, for instance ``["rx", "ro"]`` will give a ⨂ symbol.
121+
overlaid, for instance ``["rx", "ro"]`` will give a ⨂ symbol.
122122
123123
- The optional text label is placed to the right of the marker, and
124-
vertically aligned.
124+
vertically aligned.
125125
126126
- Multiple points can be marked if ``pos`` is a 2xn array or a list of
127-
coordinate pairs. In this case:
127+
coordinate pairs. In this case:
128128
129129
- all points have the same ``text`` label
130130
- ``text`` can include the format string {} which is susbstituted for the
131-
point index, starting at zero
131+
point index, starting at zero
132132
- ``text`` can be a tuple containing a format string followed by vectors
133-
of shape(n). For example::
133+
of shape(n). For example::
134134
135-
``("#{0} a={1:.1f}, b={2:.1f}", a, b)``
135+
("#{0} a={1:.1f}, b={2:.1f}", a, b)
136136
137137
will label each point with its index (argument 0) and consecutive
138138
elements of ``a`` and ``b`` which are arguments 1 and 2 respectively.
139139
140140
Example::
141141
142-
>>> from spatialmath.base import plotvol2, plot_text
142+
>>> from spatialmath.base import plotvol2, plot_point
143143
>>> plotvol2(5)
144-
>>> plot_point((0, 0)) # plot default marker at coordinate (1,2)
144+
>>> plot_point((0,0)) # plot default marker at coordinate (1,2)
145145
>>> plot_point((1,1), 'r*') # plot red star at coordinate (1,2)
146-
>>> plot_point((2,2), 'r*', 'foo') # plot red star at coordinate (1,2) and
147-
label it as 'foo'
146+
>>> plot_point((2,2), 'r*', 'foo') # plot red star at coordinate (1,2) and label it as 'foo'
148147
149148
.. plot::
150149
151-
from spatialmath.base import plotvol2, plot_text
150+
from spatialmath.base import plotvol2, plot_point
152151
ax = plotvol2(5)
153-
plot_point((0, 0))
152+
plot_point((0,0))
154153
plot_point((1,1), 'r*')
155154
plot_point((2,2), 'r*', 'foo')
156155
ax.grid()
@@ -895,13 +894,15 @@ def plot_ellipse(
895894
The ellipse is defined by :math:`x^T \mat{E} x = s^2` where :math:`x \in
896895
\mathbb{R}^2` and :math:`s` is the scale factor.
897896
898-
.. note:: For some common cases we require :math:`\mat{E}^{-1}`, for example
897+
.. note::
898+
For some common cases we require :math:`\mat{E}^{-1}`, for example:
899+
899900
- for robot manipulability
900-
:math:`\nu (\mat{J} \mat{J}^T)^{-1} \nu` i
901+
:math:`\nu (\mat{J} \mat{J}^T)^{-1} \nu` i
901902
- a covariance matrix
902-
:math:`(x - \mu)^T \mat{P}^{-1} (x - \mu)`
903-
so to avoid inverting ``E`` twice to compute the ellipse, we flag that
904-
the inverse is provided using ``inverted``.
903+
:math:`(x - \mu)^T \mat{P}^{-1} (x - \mu)`
904+
so to avoid inverting ``E`` twice to compute the ellipse, we flag that
905+
the inverse is provided using ``inverted``.
905906
906907
Returns a set of ``resolution`` that lie on the circumference of a circle
907908
of given ``center`` and ``radius``.
@@ -1150,7 +1151,7 @@ def plot_ellipsoid(
11501151
.. note::
11511152
11521153
- If a confidence interval is given then ``E`` is interpretted as a covariance
1153-
matrix and the ellipse size is computed using an inverse chi-squared function.
1154+
matrix and the ellipse size is computed using an inverse chi-squared function.
11541155
11551156
:seealso: :func:`~matplotlib.pyplot.plot_surface`, :func:`~matplotlib.pyplot.plot_wireframe`
11561157
"""

‎spatialmath/base/quaternions.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1119,7 +1119,8 @@ def q2str(
11191119
fmt: Optional[str] = "{: .4f}",
11201120
) -> str:
11211121
"""
1122-
Format a quaternion as a string
1122+
Convert quaternion to compact single-line string
1123+
11231124
11241125
:arg q: unit-quaternion
11251126
:type q: array_like(4)

‎spatialmath/base/symbolic.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ def symbol(
6161
6262
- symbols named after greek letters will appear as greek letters
6363
- underscore means subscript as it does in LaTex, so the symbols ``q``
64-
above will be subscripted.
64+
above will be subscripted.
6565
6666
:seealso: :func:`sympy.symbols`
6767
"""
@@ -347,7 +347,7 @@ def det(x):
347347
>>> R = rot2(theta)
348348
>>> print(R)
349349
>>> print(det(R))
350-
>>> simplify(print(det(R)))
350+
>>> print(simplify(det(R)))
351351
352352
.. note:: Converts to a SymPy ``Matrix`` and then back again.
353353
"""

‎spatialmath/base/transforms2d.py‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -716,13 +716,13 @@ def trnorm2(T: SE2Array) -> SE2Array:
716716
The steps in normalization are:
717717
718718
#. If :math:`\mathbf{R} = [a, b]`
719-
#. Form unit vectors :math:`\hat{b}
719+
#. Form unit vectors :math:`\hat{b}`
720720
#. Form the orthogonal planar vector :math:`\hat{a} = [\hat{b}_y -\hat{b}_x]`
721721
#. Form the normalized SO(2) matrix :math:`\mathbf{R} = [\hat{a}, \hat{b}]`
722722
723723
.. runblock:: pycon
724724
725-
>>> from spatialmath.base import trnorm, troty
725+
>>> from spatialmath.base import trnorm2, trot2
726726
>>> from numpy import linalg
727727
>>> T = trot2(45, 'deg', t=[3, 4])
728728
>>> linalg.det(T[:2,:2]) - 1 # is a valid SO(3)
@@ -797,8 +797,8 @@ def tr2adjoint2(T):
797797
>>> tr2adjoint2(T)
798798
799799
:Reference:
800-
- Robotics, Vision & Control for Python, Section 3.1, P. Corke, Springer 2023.
801-
- `Lie groups for 2D and 3D Transformations <http://ethaneade.com/lie.pdf>_
800+
- *Robotics, Vision & Control for Python*, Section 3.1, P. Corke, Springer 2023.
801+
- `*Lie groups for 2D and 3D Transformations* <http://ethaneade.com/lie.pdf>`_
802802
803803
:SymPy: supported
804804
"""
@@ -899,14 +899,14 @@ def trinterp2(start, end, s, shortest: bool = True):
899899
:rtype: ndarray(3,3) or ndarray(2,2)
900900
:raises ValueError: bad arguments
901901
902-
- ``trinterp2(None, T, S)`` is an SE(2) matrix interpolated
903-
between identity when `S`=0 and `T` when `S`=1.
904-
- ``trinterp2(T0, T1, S)`` as above but interpolated
905-
between `T0` when `S`=0 and `T1` when `S`=1.
906-
- ``trinterp2(None, R, S)`` is an SO(2) matrix interpolated
907-
between identity when `S`=0 and `R` when `S`=1.
908-
- ``trinterp2(R0, R1, S)`` as above but interpolated
909-
between `R0` when `S`=0 and `R1` when `S`=1.
902+
- ``trinterp2(None, T, s)`` is an sE(2) matrix interpolated
903+
between identity when `s=0` and `T` when `s=1`.
904+
- ``trinterp2(T0, T1, s)`` as above but interpolated
905+
between `T0` when `s=0` and `T1` when `s=1`.
906+
- ``trinterp2(None, R, s)`` is an sO(2) matrix interpolated
907+
between identity when `s=0` and `R` when `s=1`.
908+
- ``trinterp2(R0, R1, s)`` as above but interpolated
909+
between `R0` when `s=0` and `R1` when `s=1`.
910910
911911
.. note:: Rotation angle is linearly interpolated.
912912

‎spatialmath/base/transforms3d.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,7 @@ def transl(x, y=None, z=None):
326326
.. note:: This function is compatible with the MATLAB version of the
327327
Toolbox. It is unusual/weird in doing two completely different things
328328
inside the one function.
329+
329330
:seealso: :func:`~spatialmath.base.transforms2d.transl2`
330331
:SymPy: supported
331332
"""
@@ -3390,7 +3391,8 @@ def tranimate(T: Union[SO3Array, SE3Array], **kwargs) -> str:
33903391
:type wait: bool
33913392
:param movie: name of file to write MP4 movie into
33923393
:type movie: str
3393-
:param **kwargs: arguments passed to ``trplot``
3394+
:param kwargs: arguments passed to ``trplot``
3395+
:type kwargs: dict
33943396
33953397
- ``tranimate(T)`` where ``T`` is an SO(3) or SE(3) matrix, animates a 3D
33963398
coordinate frame moving from the world frame to the frame ``T`` in

0 commit comments

Comments
 (0)