Repository navigation
API docs fix - #1822
API docs fix#1822erogluorhan wants to merge 8 commits into
Conversation
The API reference page mixes conventions: Grid/UxDataArray/UxDataset are top-level sections in some places and subsections of a topic (Plotting, Subsetting, Remapping, ...) in others, which makes the page hard to navigate. Add a `.. sectnum::` directive so Docutils numbers every heading on the page down to depth 3. The hierarchy is now explicit both in the headings themselves and in the page contents sidebar, and the numbering stays correct when sections are added, removed, or reordered. Note that Sphinx keeps the page title as a section, so Docutils counts it as the first level: headings read "1.3 Grid" / "1.3.1 Constructors" rather than "3. Grid" / "3.1. Constructors". Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The sidebar entry for the API reference expanded into a list of `uxarray.grid.neighbors.DataArrayNeighborhood.*` stub pages instead of staying collapsed like every other entry. Those stubs are the pages `autosummary` writes for `:toctree: generated/`, and it files each one under the page that summarised it. `sphinx_remove_toctrees` was supposed to prune them, which is why only part of them showed up: it removes toctree nodes while `findall` is still iterating over the document, and docutils' `findall` is a generator, so removing a node makes it skip the siblings that follow. One of the 43 toctrees on the API reference page was skipped every build, and its 14 entries leaked into the sidebar. Replace the extension with a `env-updated` handler that materializes the node list before touching the tree, and drop the dependency. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The heading rendered but its table was always empty: `RemapWeights` is exported from `uxarray.remap`, not from the top-level `uxarray` package, so under `.. currentmodule:: uxarray` autosummary could not import it and silently dropped the entry. Summarise it as `remap.RemapWeights`, matching how the page already refers to `grid.intersections.*` and `utils.computing.*`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
@dylannelson @Sevans711 I put this together with Claude to have a starting point to see all points discussed in #1815. Let me know what you think. |
Sevans711
left a comment
Sevans711
left a comment
There was a problem hiding this comment.
It was easiest for me to reply with a review. Even though the PR is marked as draft I do think it looks ready for review, in fact I also think it is almost ready to merge!
This technically solves all of the underlying issues mentioned in #1815:
- Sections are now numbered on the API docs page.
- The API reference sidebar no longer expands just to show neighborhood methods.
- The "Remapping" section's "Helpers" subsection no longer renders as empty.
It would be okay to merge as-is. I left one tiny non-blocking inline comment, plus I have a couple of small style notes below:
- (1A) Section numbering all starts with 1, which adds a lot of unnecessary "1." throughout the page, e.g. "1.2 Tutorial", "1.3 Grid", "1.3.1 Constructors"
- (1B) Section numbering has only a single space between the number and the title, which can be a bit jarring.
If it doesn't take too much effort to clean this up a bit, I think it could be worthwhile to bring the style more in line with what was originally proposed, e.g. "2. Tutorial", "3. Grid", "3.1. Constructors". (Or, maybe use parentheses, like "(3.1) Constructors"?)
| # Allow for changes to be made to the css in the theme_overrides file | ||
| def setup(app): | ||
| app.add_css_file("theme_overrides.css") | ||
| app.connect("builder-inited", update_gallery) | ||
| app.connect("env-updated", prune_generated_toctrees) |
There was a problem hiding this comment.
The comment here is now extra stale; it looks like it describes the whole setup() function but it actually only describes the app.add_css_file line.
Could remove it, update it to explain all 3 things here, or move it inside setup() to be directly next to the app.add_css_file line.
There was a problem hiding this comment.
Good catch! Now moved it into setup() before the single line it is referring to
Sphinx keeps a page's title as a section of its own rather than promoting it to a document title, so Docutils' `.. sectnum::` counted "API reference" as the first level and numbered every heading on the page "1.something" -- "1.2 Tutorial", "1.3.1 Constructors". Replace the directive with a `NumberSections` transform that numbers the sections below the title instead, giving "2. Tutorial" and "3.1. Constructors". The trailing period plus a small CSS nudge separate the number from the heading, since Docutils' HTML writer collapses its own no-break-space padding to a single regular space. Also move the theme_overrides comment inside setup(), next to the add_css_file line it actually describes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…rogluorhan_api_docs_fix
Thanks @Sevans711 ! This is great feedback, and I believe I've now covered all of them (1A and 1B). Please have a look and let me know. |
Closes #1815
Overview
This PR addresses three issues mentioned in the linked issue:
.. sectnum::directive.PR Checklist
General
Documentation and Examples
docs/api.rst; internal (private) function names start with an underscore (_)AI Disclosure
AI Usage:
Claude Opus 5