petercorke / petercorke/robotics-toolbox-python
Docs/Sphinx cleanup and blocks/ type hints
Nobody has claimed this yet.
- 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/*.pyfor 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), apath-returning method and a gripper/end-effector method (three consecutive:returns:each), one ofBaseRobot'sq-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 bareSee AlsoNumPy-style heading (underlined with----) still appears 48 times across 6 files -- each one a latent instance of the Napoleon/sphinx_autodoc_typehintsconflict 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, outsidetools/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 tocoal. This is prose adapted from the ICRA2021 paper, not a plain install matrix, so it needs a deliberate rewrite (describingcoal'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 forcoalon 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) definingbdsimblock classes have essentially no type hints (arm.pyalone has 16 untyped__init__methods) -- unlike the rest of the codebase's modern-syntax convention. Real consequence already hit once:blocks/arm.py'sgravityparameter docstring claimedfloatbut the actual runtime value is always a 3-vector passed straight toRobot.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 ifblocks/sees more maintenance.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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