Generate API reference with autodoc2, add class-hierarchy and object-model diagrams

.github/workflows/deploy-book.yml

@@ -21,6 +21,10 @@ jobs:
       with:
         python-version: 3.x
 
+    - name: Install Graphviz (for API inheritance diagrams)
+      run: |
+        sudo apt-get update && sudo apt-get install -y graphviz
+
     - name: Install dependencies
       run: |
         pip install -r docs/requirements.txt
@@ -36,28 +40,45 @@ jobs:
 
     # Build the book
     - name: Build the book
+      env:
+        ABTEM_DOCS_VERSION: stable
       run: |
         jupyter book build docs
-    
+
     - name: Upload book
       uses: actions/upload-artifact@v7
       with:
         name: html-pages
         path: ./docs/_build/html
 
-  # Push the book's HTML to github-pages
+  # Push the book's HTML to the root of github-pages, keeping the /dev/
+  # docs (published separately by deploy-dev.yml) intact.
   deploy-book:
     needs: build-book
     runs-on: ubuntu-latest
+    concurrency:
+      group: gh-pages-push
     steps:
       - name: Retrieve release distributions
         uses: actions/download-artifact@v8
         with:
           name: html-pages
-          path: ./docs/_build/html
+          path: ./site
+
+      - name: Check out current gh-pages
+        uses: actions/checkout@v7
+        with:
+          ref: gh-pages
+          path: gh-pages-current
+
+      - name: Preserve /dev/ docs in the new snapshot
+        run: |
+          if [ -d gh-pages-current/dev ]; then
+            cp -R gh-pages-current/dev ./site/dev
+          fi
 
       - name: GitHub Pages action
         uses: peaceiris/actions-gh-pages@v4.1.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs/_build/html
+          publish_dir: ./site

.github/workflows/deploy-dev.yml

@@ -0,0 +1,59 @@
+# Publishes the development documentation (built from main) under /dev/ on
+# gh-pages. The stable docs at the site root are published by deploy-book.yml
+# on each release and are the default readers see.
+
+name: deploy-dev-docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "scripts/**"
+      - ".github/workflows/deploy-dev.yml"
+  workflow_dispatch: {}
+
+# Only the newest dev build per push burst needs to deploy.
+concurrency:
+  group: deploy-dev
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Set up Python 3.x
+      uses: actions/setup-python@v6
+      with:
+        python-version: 3.x
+
+    - name: Install Graphviz (for API inheritance diagrams)
+      run: |
+        sudo apt-get update && sudo apt-get install -y graphviz
+
+    - name: Install dependencies
+      run: |
+        pip install -r docs/requirements.txt
+
+    - name: Strip orphaned ipywidgets state
+      run: |
+        python scripts/check_notebook_widgets.py --fix
+
+    - name: Build the book (dev)
+      env:
+        ABTEM_DOCS_VERSION: dev
+      run: |
+        jupyter book build docs
+
+    - name: Deploy to /dev/
+      uses: peaceiris/actions-gh-pages@v4.1.0
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html
+        # destination_dir makes this deploy replace only /dev/, leaving the
+        # stable site at the root untouched. NEVER add force_orphan here:
+        # combined with destination_dir it would replace the whole branch
+        # with only /dev/, wiping the root site.
+        destination_dir: dev

.gitignore

@@ -70,7 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-**/_autosummary
+docs/reference/api/apidocs/
 
 # PyBuilder
 target/

.readthedocs.yml

@@ -4,6 +4,8 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.13"
+  apt_packages:
+    - graphviz
   jobs:
     pre_build:
       # Generate the Sphinx configuration for this Jupyter Book so it builds.

docs/_config.yml

@@ -5,7 +5,7 @@ title: ""
 author: ""
 copyright: ""
 logo: images/logo.png
-exclude_patterns: ["_templates", "_ext", "_build", "reference/benchmarks"]
+exclude_patterns: ["_ext", "_build", "reference/benchmarks"]
 only_build_toc_files: false
 
 # Force re-execution of notebooks on each build.
@@ -24,9 +24,9 @@ bibtex_bibfiles:
 
 # Information about where the book exists on the web
 repository:
-  url: https://github.com/executablebooks/jupyter-book  # Online location of your book
+  url: https://github.com/abTEM/doc  # Online location of your book
   path_to_book: docs  # Optional path to your book, relative to the repository root
-  branch: master  # Which branch of the repository should be used when creating links (optional)
+  branch: main  # Which branch of the repository should be used when creating links (optional)
 
 # Add GitHub buttons to your book
 # See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository
@@ -37,17 +37,22 @@ html:
 
 sphinx:
   extra_extensions:
-  - 'sphinx.ext.autodoc'
-  - 'sphinx.ext.napoleon'
   - 'sphinx.ext.viewcode'
-  - 'sphinx.ext.autosummary'
-  - 'sphinx_autodoc_typehints'
+  - 'sphinx.ext.inheritance_diagram'
   - 'matplotlib.sphinxext.roles'
+  - 'autodoc2'
   local_extensions:
     abtem_version_footer: _ext
+    abtem_autodoc2: _ext
   config:
-    autosummary_generate: true
-    templates_path: [ "_templates" ]
+    autodoc2_render_plugin: "myst"
+    autodoc2_output_dir: "reference/api/apidocs"
+    autodoc2_hidden_objects: ["private", "dunder", "inherited"]
+    autodoc2_skip_module_regexes: [".*\\._.*"]
+    # Skip the generated index.rst wrapper page (just a toctree + footnote) -
+    # api.md links straight to the abtem package page instead.
+    autodoc2_index_template: null
     suppress_warnings: ["etoc.toctree"]
+    graphviz_output_format: "svg"
   html_context:
     default_mode: light

docs/_ext/abtem_autodoc2.py

@@ -0,0 +1,24 @@
+"""Point sphinx-autodoc2 at the installed abTEM package.
+
+The package location differs between environments (editable checkout locally,
+site-packages on CI and Read the Docs), so the path is resolved at build time
+from the abtem import rather than hardcoded in _config.yml.
+"""
+
+import os
+
+
+def _set_autodoc2_packages(app, config):
+    import abtem
+
+    pkg_dir = os.path.dirname(os.path.abspath(abtem.__file__))
+    # autodoc2 requires the path relative to the Sphinx source dir, POSIX-style
+    rel_path = os.path.relpath(pkg_dir, app.srcdir).replace(os.sep, "/")
+    config.autodoc2_packages = [
+        {"path": rel_path, "module": "abtem", "auto_mode": True}
+    ]
+
+
+def setup(app):
+    app.connect("config-inited", _set_autodoc2_packages)
+    return {"parallel_read_safe": True, "parallel_write_safe": True}

docs/_ext/abtem_version_footer.py

@@ -1,7 +1,23 @@
 """Show the installed abTEM version (the one the docs were built/tested against)
 in the page footer, replacing the theme's static copyright notice.
+
+Also handles the stable/dev docs versions published on GitHub Pages: the
+ABTEM_DOCS_VERSION environment variable ("stable" when unset, so local and
+Read the Docs builds behave like today) selects between the stable build at
+the site root and the development build served under /dev/. Dev builds get a
+warning banner linking back to stable and a robots noindex tag; stable builds
+get a footer link to the dev docs.
 """
 
+import os
+
+STABLE_URL = "https://abtem.github.io/doc/"
+DEV_URL = STABLE_URL + "dev/"
+
+
+def _is_dev():
+    return os.environ.get("ABTEM_DOCS_VERSION", "stable") == "dev"
+
 
 def _set_abtem_version_footer(app, config):
     try:
@@ -12,14 +28,37 @@ def _set_abtem_version_footer(app, config):
         version = "unknown"
 
     theme_options = dict(config.html_theme_options or {})
-    theme_options["extra_footer"] = (
+    footer = (
         "<p>Tested against "
         '<a href="https://github.com/abTEM/abTEM">abTEM</a>'
-        f" v{version}.</p>"
+        f" v{version}."
     )
+    if _is_dev():
+        theme_options["announcement"] = (
+            "This is the <strong>development</strong> documentation, built from "
+            f'the latest main branch. <a href="{STABLE_URL}">Switch to the '
+            "stable version</a>."
+        )
+        footer += " Development build."
+    else:
+        footer += (
+            f' Also available: <a href="{DEV_URL}">development version</a>.'
+        )
+    footer += "</p>"
+    theme_options["extra_footer"] = footer
     config.html_theme_options = theme_options
 
 
+def _add_noindex(app, pagename, templatename, context, doctree):
+    # Keep the dev docs out of search results so readers land on stable.
+    if _is_dev():
+        context["metatags"] = (
+            context.get("metatags", "")
+            + '\n    <meta name="robots" content="noindex">'
+        )
+
+
 def setup(app):
     app.connect("config-inited", _set_abtem_version_footer)
+    app.connect("html-page-context", _add_noindex)
     return {"parallel_read_safe": True, "parallel_write_safe": True}

docs/_toc.yml

@@ -50,6 +50,8 @@ parts:
   - caption: Reference
     chapters:
       - file: reference/api/api
+        sections:
+          - file: reference/api/class_diagrams
       - file: reference/config
       # - file: reference/glossary
   - caption: abTEM