petercorke / petercorke/robotics-toolbox-python

Docs/Sphinx cleanup and blocks/ type hints

Open
#574 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

tech-debt
Dominant language
C++
Stars
3.5k
Forks
624
Avg merge
2d 4h
Merged PRs (30d)
53

Description

Migrated from tech-debt.md (deleted, see repo history via git log -- tech-debt.md). Groups docstring/Sphinx and type-hint hygiene sweeps.

  • Sweep robot/*.py for repeated :returns:/:param: field markers. Repeated field names don't trigger a Sphinx/docutils warning (silently accepted) but are still wrong. Known instances: BaseRobot.hasdynamics/hascollision (two consecutive :returns:), BaseRobot.ets (duplicated :param :param start:/:param :param end:, stray trailing colon), BaseRobot.todegrees (six consecutive :returns: lines), a path-returning method and a gripper/end-effector method (three consecutive :returns: each), one of BaseRobot's q-random methods (:returns: ... :rtype: ... crammed onto one line). Fix: grep ^\s*:returns:.*\n\s*:returns: (and :param:) and manually merge each into a single well-formed field -- needs a human read of intent, not a mechanical script.

  • Systematic sweep: bare NumPy-style section headers → explicit reST directives, codebase-wide. The codebase is mid-migration from NumPy-style docstrings to reST fields. :seealso: is used 202 times (the intended convention), but the vestigial bare See Also NumPy-style heading (underlined with ----) still appears 48 times across 6 files -- each one a latent instance of the Napoleon/sphinx_autodoc_typehints conflict that broke the Sphinx build once already (BaseRobot.dotfile, fixed by converting to .. rubric:: Notes). Likely true for other NumPy-recognized headers too (Notes, Warning, Raises, Attributes, Examples). Grep ^\s*(Notes?|Warnings?|Parameters|Returns|Raises|Yields|Attributes|Methods|References|See Also|Examples)\s*$ followed by a matching -+ underline, outside tools/urdf/ (which has genuine vendored NumPy-style docstrings Napoleon correctly converts -- don't touch those), and convert each to its reST equivalent.

  • Rewrite intro.rst's "Collision checking" section. Still describes PyBullet ("dramatically improved... using [PyBullet]_", plus a [PyBullet]_ citation) even though the collision backend switched to coal. This is prose adapted from the ICRA2021 paper, not a plain install matrix, so it needs a deliberate rewrite (describing coal's GJK/EPA, CollisionObject/BVHModelOBBRSS, primitive shapes) rather than a mechanical find-replace, plus updating/dropping the [PyBullet]_ reference and noting collision checking is Linux/macOS-only via pip (no Windows wheels for coal on PyPI -- conda-forge has them, that's an accepted, deliberate gap, not itself something to fix).

  • Add type hints throughout src/roboticstoolbox/blocks/. 5 files (arm.py, mobile.py, quad_model.py, spatial.py, uav.py) defining bdsim block classes have essentially no type hints (arm.py alone has 16 untyped __init__ methods) -- unlike the rest of the codebase's modern-syntax convention. Real consequence already hit once: blocks/arm.py's gravity parameter docstring claimed float but the actual runtime value is always a 3-vector passed straight to Robot.rne()/gravload() -- nothing caught the mismatch because there was no annotation to check against. Not urgent standalone, but worth doing opportunistically whenever a block class is touched, and worth a dedicated pass if blocks/ sees more maintenance.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the listed robot/*.py docstrings and the grep patterns in the issue, then inspect intro.rst and the five files under src/roboticstoolbox/blocks/. Exclude tools/urdf/ from the NumPy-style heading sweep. Done means repeated fields and headings are corrected, the collision section matches coal and its references/platform note are updated, and the block classes have appropriate type hints.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation, tooling
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.