Reorganize Python API docs: grouped class index and enum reference#163
Merged
Conversation
Switch the Python API docs from sphinx_automodapi to sphinx.ext.autosummary and reorganize the ~140-class flat list into a category-grouped index. - Add generate_class_index.py, which produces the GeneratedClasses.rst landing page and one api_categories/ page per functional group. - Add a custom autosummary class template that omits private and dunder members (any name starting with '_') and the recursive Value/ValueArray typing aliases on PdmObjectBase. - Set toc_object_entries = False so documented objects no longer appear as redundant leaf nodes in the navigation sidebar. - Expand the protobuf structure reference in ProtobufStructures.rst.
The ~44 StrEnum classes in rips.generated.generated_classes (BetaFactorType, CompletionType, etc.) define the value sets accepted by various API fields and command parameters, but were not in rips.__all__ and so went undocumented. - Extend generate_class_index.py to discover StrEnum subclasses directly from the generated module and render EnumClasses.rst, one autoclass block per enum so every allowed value is listed. - Add EnumClasses to the index toctree.
Sort the classes that fell into the "Other Classes" catch-all into real groups and consolidate the two fracture categories. - CellPropertyFilter, CellRangeFilter, DataFilterCollection and PropertyFilter -> Cell Filters and Intersections. - RimPolygonContainer -> Annotations and Polygons. - PdmNestedCollectionBase -> Base Classes. - Route the StrEnum proto enums (PropertyType, PropertyDataType, NNCPropertyType) to the enum reference page instead of the class index: discover_classes() now excludes StrEnum subclasses and discover_enums() scans the whole rips namespace. - Merge the "Fracture Models" category into "Fractures".
Place the Python Examples page directly after Installation so readers reach worked examples before the API reference sections.
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
Reworks the structure of the
ripsPython API documentation.sphinx_automodapiwithsphinx.ext.autosummary. A newgenerate_class_index.pyproduces a category-grouped class index — theGeneratedClasses.rstlanding page plus oneapi_categories/page per functional group — instead of a single flat ~140-class table._) from the generated class pages.toc_object_entries = Falseso documented objects no longer appear as redundant leaf nodes in the navigation sidebar.EnumClasses.rstreference page documenting the 47StrEnumparameter types (BetaFactorType,CompletionType, …), discovered fromrips.generated.generated_classesandrips.enums.ProtobufStructures.rst.Testing
A clean
sphinx-build -M html docs/source docs/buildsucceeds (109 warnings, all pre-existing).🤖 Generated with Claude Code