Generate API reference with autodoc2, add class-hierarchy and object-model diagrams#9
Open
TomaSusi wants to merge 8 commits into
Open
Generate API reference with autodoc2, add class-hierarchy and object-model diagrams#9TomaSusi wants to merge 8 commits into
TomaSusi wants to merge 8 commits into
Conversation
Stable (release-built) docs remain the default at the site root; a new deploy-dev workflow publishes main to /dev/ on every docs push. The two versions cross-link via the footer (stable -> dev) and an announcement banner (dev -> stable), and dev pages carry a robots noindex tag so search engines only surface stable. The release deploy now carries the existing /dev/ tree forward so the two publish cadences don't clobber each other. Also tidies docs/requirements.txt (duplicates, unused sphinx_rtd_theme/ nbsphinx), removes the dead doc_requirements.txt, and points the repository buttons at abTEM/doc instead of the jupyter-book template. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
sphinx-autodoc2 (extension mode, auto_mode off) with a small custom docutils parser that runs numpy-style docstrings through napoleon. autodoc2_test.md renders abtem.waves.Probe both ways: default rST parsing turns numpy sections into page headings; the napoleon bridge produces field lists identical to the current autodoc output. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replaces the eval-rst autosummary tree (and its custom templates) with sphinx-autodoc2: MyST-native module pages generated into reference/api/apidocs/ at build time (gitignored). A local extension resolves the installed abtem package path at build time so the same config works locally, on CI, and on Read the Docs. The two inline autosummary tables in reference/config.md become autodoc2-summary directives with abtem.config.* aliases. Drops now-unused autodoc, napoleon, autosummary, and typehints extensions, the napoleon-bridge parser, and the experiment test page. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
autodoc2's index.rst only held a toctree + footnote pointing at the single top-level package; api.md now links straight to the abtem package page, removing one navigation hop between the API sidebar item and real content. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
sphinx.ext.inheritance_diagram (+ Graphviz) renders inheritance trees for the five core class families (wave functions, potentials, detectors, scan patterns, CTF) at the top of the API landing page, as a quick map before the exhaustive autodoc2 tree. Diagram nodes link directly into the matching autodoc2-generated class pages, since both share the same Sphinx py-domain object inventory. Graphviz's dot binary is now a build dependency: installed via apt in both GitHub Actions workflows and via .readthedocs.yml apt_packages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Inline SVG (theme-aware via pydata-sphinx-theme CSS variables, works in both light and dark mode) showing how PlaneWave/Probe, Potential, and the multislice/scan operations connect to produce the six simulation modes documented below it, right where the existing 'abTEM object model' prose already describes this in words. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…rows Probe is a Wave function like PlaneWave, so scan(potential, scan, detectors) now leaves from the same box instead of a separate Probe box. Potential now visibly feeds both multislice(potential) and scan(...) via a dashed drop-line with junction dots where it meets each arrow, rather than sitting disconnected above the pipeline. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The five inheritance diagrams pushed the full autodoc2 reference tree far down the API landing page. They now live on their own sub-page (reference/api/class_diagrams.md), registered as an explicit _toc.yml section under API so it's not the page that opens by default - api.md stays a short landing page linking to it, with the full reference immediately below. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3 tasks
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
Generates the API reference with sphinx-autodoc2 instead of
sphinx.ext.autosummary, and adds two new diagrams to help readers orient in the API. Builds on top of #8 (based on that branch) — once #8 merges, this PR's diff will shrink to just the commits below.auto_mode, default docstring parsing): replaces theeval-rstautosummary tree and its custom templates. Pages generate intodocs/reference/api/apidocs/at build time (gitignored);docs/_ext/abtem_autodoc2.pyresolves the installedabtempackage path so it works locally, on CI, and on Read the Docs.index.rstwrapper page (autodoc2_index_template: null) — the "API" sidebar item now links straight to theabtempackage page instead of through an empty intermediate page.sphinx.ext.inheritance_diagram+ Graphviz) for the five core class families (wave functions, potentials, detectors, scan patterns, CTF), moved to their own sub-page (reference/api/class_diagrams.md) so they don't push the full reference tree down the main API landing page. Diagram nodes link directly into the matching autodoc2 pages.PlaneWave/Probe,Potential, and themultislice/scanoperations connect to produce the six simulation modes documented right below it.dotbinary is now a build dependency — added to both GitHub Actions workflows and.readthedocs.yml(apt_packages).A separate, unmerged
jb2branch has a no-go assessment of migrating to Jupyter Book 2 outright (mystmd has no autodoc equivalent yet) — this PR stays on Jupyter Book 1, using autodoc2 purely as a Sphinx extension.Test plan
🤖 Generated with Claude Code