fix(docs): resolve reST syntax and structural Sphinx build warnings#540
Open
petercorke wants to merge 3 commits into
Open
fix(docs): resolve reST syntax and structural Sphinx build warnings#540petercorke wants to merge 3 commits into
petercorke wants to merge 3 commits into
Conversation
…llback tests
roboticstoolbox/robot/ETS.py defines a class also called ETS, and
robot/__init__.py's `from ...ETS import ETS` rebinds the "ETS"
attribute on the roboticstoolbox.robot package to the class, shadowing
the submodule of the same name. Python 3.10's unittest.mock resolves
dotted-string patch targets via plain getattr (falling back to import
only on AttributeError), so patch("...ETS.ETS_fkine", ...) resolved
"ETS" to the shadowing class and failed with AttributeError; 3.11+
uses pkgutil.resolve_name and isn't fooled by the same shadowing. This
is why it only ever showed up on Python 3.10 in CI.
Not a real code bug - the actual fknm/facade fallback machinery was
always fine, only the test's patch target resolution was broken on
3.10. Fixed by looking up the real module via sys.modules directly
(the only lookup with no getattr involved) and patching against that
with patch.object() instead of a dotted string.
Rehearsed: all 41 tests in test_fknm_fallback.py pass under both
Python 3.10 and 3.13.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Cross-references the fknm fallback test fix in this same branch. Python 3.10 reaches EOL October 2026 — flag this specific workaround for removal (and a general 3.10-specific-code sweep) at that point. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Full docs build went from 216 warnings/errors down to 5 (the deferred KinematicCache/SensorBase/jointset items, left for the runblock-code pass). Fixes span: - Jinja2 filter-precedence bug in the autosummary method template ((class + '.' + name) | escape | underline) — the filter chain was only sizing the title underline to the method name, not the full "Class.method" title, breaking all 39 generated IK stub pages. - Duplicate object descriptions (ik_GN/ik_LM/ik_NR/ikine_GN/ikine_LM documented both inline and via IK/stubs/) via :no-index: in the stub template. - A broken Examples/.. runblock:: docstring template repeated across BaseRobot.py, ETS.py, Link.py, ET.py, Dynamics.py: missing blank lines before Examples/See Also, and un-indented runblock directive bodies (making those examples inert — never actually executed). - 7 malformed reST tables in DHRobot.py/RobotKinematics.py sharing one column-width overflow bug (``iterations`` wider than its border). - A genuine Napoleon + sphinx_autodoc_typehints conflict: bare NumPy-style "Note" headers mixed into otherwise-reST docstrings, root-caused via an isolated minimal Sphinx build bisecting the extension list. Confirmed Napoleon is still needed (tools/urdf/*.py has real vendored NumPy-style docstrings) — fixed by converting the two affected Note headers to .. rubric:: Notes instead. - Assorted one-offs: a Markdown-style pipe table misparsed as reST substitution syntax, unclosed inline literals/interpreted text, under/over-indented bullet continuations breaking list structure, a bare URL parsed as an implicit hyperlink target, an incomplete list-table row, `**kwargs` in a field name misparsed as bold markup, a nested bullet list missing its blank-line separator. - Removed two pieces of dead config: suppress_warnings' non-existent "duplicate" token (replaced with the real "ref.citation"), and napoleon_custom_sections listing an unused "Synopsis" section. Logged two tech-debt entries for what's deliberately left for later: repeated :returns:/:param: fields that don't trigger warnings but are still wrong, and the broader NumPy-to-reST docstring migration debt (48 vestigial "See Also" headers across 6 files sharing the same Napoleon-conflict risk class as the Note bug). Verified via a full local Sphinx build after each round of fixes, not just spot-checking individual warnings. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Full docs build went from 216 warnings/errors down to 5 (the deferred
KinematicCache/SensorBase/jointsetitems, left for a follow-up runblock-code pass).ik_GN/ik_LM/ik_NR/ikine_GN/ikine_LM) via:no-index:in the stub template.Examples/.. runblock::docstring template repeated acrossBaseRobot.py,ETS.py,Link.py,ET.py,Dynamics.py: missing blank lines and un-indented directive bodies (making those examples inert — never actually executed).Napoleon+sphinx_autodoc_typehintsconflict (bare NumPy-styleNoteheaders), root-caused via an isolated minimal Sphinx build. Confirmed Napoleon is still needed (tools/urdf/*.pyhas real vendored NumPy-style docstrings) — fixed the two affectedNoteheaders instead of removing the extension.list-tablerow,**kwargsmisparsed as bold.suppress_warnings's bogus"duplicate"token, unusednapoleon_custom_sections).Two tech-debt entries logged for what's deliberately deferred: repeated
:returns:/:param:fields, and the broader NumPy→reST docstring migration debt (48 vestigialSee Alsoheaders across 6 files).Test plan
python -m ast.parseon every modified file🤖 Generated with Claude Code