Publish versioned docs: stable at root, dev under /dev/

.github/workflows/deploy-book.yml

@@ -36,28 +36,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,55 @@
+# 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 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

docs/_config.yml

@@ -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

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/requirements.txt

@@ -1,8 +1,4 @@
 abtem
 jupyter-book<2
-sphinx_autodoc_typehints
-docutils
-jupyter-book
-sphinx_rtd_theme
-nbsphinx
 sphinx-autodoc-typehints
+docutils