docs: API reference cleanup - #39
Merged
Merged
Conversation
…page Add docstrings for Shape/Axes/Arrow/Path/CollisionShape/Box properties and for the SceneNode, SceneGroup, Shape, and CollisionShape base classes, none of which had any before. Fix a pre-existing wrong return type annotation on SceneNode.scene_parent while in there. Rework docs/source/api.rst: add a class inheritance diagram, a class summary table for the four base classes (via autosummary :toctree:, so each gets a real linkable page), and convert the leaf shape classes from blanket automodule directives to explicit autoclass entries so their :class: cross-references resolve to the public spatialgeometry.X path instead of silently failing to link against the internal geom.* module path. Add a custom autosummary/class.rst template so the generated base class pages show full member docs instead of Sphinx's default thin summary-only table. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Brings in the full PR batch landed today (jhavl#19-jhavl#25, jhavl#27, jhavl#29-jhavl#32). Three conflicts, all in code this branch's own doc-focused commits had touched: - CollisionShape.py: Mesh's filename/scale docstring -- this branch's copy predated jhavl#19/jhavl#22, took origin/main's newer/complete version (adds color, y_up params). - SceneGroup.py: this branch's copy predated jhavl#21's list-wiring rewrite entirely (old **kwargs-only constructor) -- took origin/main's version wholesale. - Shape.py: two independently-written class docstrings, not a stale/current split -- kept this branch's own prose since it's the one actively being authored here. WIP (uncommitted doc edits) was stashed before this merge and not yet reapplied.
…toclass fixes - New fileformats.rst: mesh file format support matrix (Swift vs trimesh, the 5-format overlap, per-format history/tradeoffs, a summary table) - conf.py: autoclass_content='both' so each class's __init__ docstring (pose/color/stype/base, previously invisible on every subclass page) merges with its class docstring; case-insensitive alphabetical member sort; "Inherited from X" labels on inherited members; GitHub link in footer (_templates/footer.html) - api.rst: added Ellipsoid/CollisionShapeGroup to the inheritance diagram, excluded the deprecated collided() method from every CollisionShape subclass page including CollisionShapeGroup - intro.rst: substantially reworked -- consistent `from spatialgeometry import X` style instead of `import ... as sg/gm`, fixed several stale/ incorrect passages (a launch()/pose mix-up, invalid matplotlib color names, a broken table.T *= SE3(...) example), documented the SceneGroup list-membership/scene_parent equivalence Depends on jhavl#38 (adds the update() method the scene-graph examples now call) -- these runblocks won't build clean until that merges. - SceneNode/SceneGroup/CollisionShape/Shape docstrings: reordered to precis -> params -> expanded description throughout; added missing :param: entries (initlist on the two group classes); Mesh's color override moved from a redundant :param: into a proper .. note::; removed duplicate pose entries on Axes/Arrow/Path - examples/: consolidated animating_shapes.py/displaying_shapes.py/ scene_graph.py into cube.py/mesh.py/room.py
…eanup # Conflicts: # docs/source/intro.rst
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
A broad pass over the Sphinx docs and a few examples, prompted by reviewing
the API reference end-to-end.
New
fileformats.rst: which mesh file formats Swift (three.js) andtrimesh/Coal each support, the 5-format overlap that works for both
display and collision, per-format history/tradeoffs, and a summary table.
conf.py:autoclass_content = 'both'so each class's__init__docstring (
pose/color/stype/base-- previously invisible on everysubclass page, since Sphinx's default only shows the class docstring) now
merges in; case-insensitive alphabetical member sort; "Inherited from X"
labels on inherited members; a GitHub link in the footer.
api.rst: addedEllipsoid/CollisionShapeGroupto the inheritancediagram (was missing); excluded the deprecated
collided()method fromevery
CollisionShapesubclass page, includingCollisionShapeGroup(previously missed).
intro.rst: reworked throughout -- consistentfrom spatialgeometry import Xstyle instead of mixedimport ... as sg/as gm; fixed alaunch()/posemix-up (launch()doesn't exist in this package, thatwas a leftover reference to Swift's unrelated method), invalid matplotlib
color names in a runnable example, and a broken
table.T *= SE3(...)example (in-place multiply with an
SE3operand silently does elementwisemath, not pose composition); documented the
SceneGrouplist-membership/
scene_parentequivalence people can otherwise trip over.Depends on #38 --
the scene-graph examples now call the new
update()method, so those tworunblocks won't build clean until that merges.
Docstrings (
SceneNode/SceneGroup/CollisionShape/Shape):reordered to precis -> params -> expanded description throughout; added
missing
:param:entries (initliston the two group classes);Mesh'scolor-override behavior moved from a redundant/conflicting
:param:entryinto a proper
.. note::; removed duplicateposeentries that haddrifted onto
Axes/Arrow/Path.examples/: consolidatedanimating_shapes.py/displaying_shapes.py/scene_graph.pyintocube.py/mesh.py/room.py(one of the originalsmoved to Swift's own examples instead).
Test plan
make html-- builds clean against a temporarily-installed copy offix: rename _propogate_scene_* to _propagate_scene_* (was misspelled) #38's branch (2 pre-existing warnings, same baseline, no new ones);
against
mainas-is, the twoupdate()-calling runblocks inintro.rstwill fail until fix: rename _propogate_scene_* to _propagate_scene_* (was misspelled) #38 merges
Cuboid/Mesh/CollisionShapeGroup/SceneGrouppages -- params merge correctly, no duplicate/dangling entriestable.T *= SE3(...)fix's underlying claim live (numpyelementwise vs. matrix-multiply semantics) before rewriting that example