From 51b5f553fb5dc192b2f52dacc3b53dd5d7028b00 Mon Sep 17 00:00:00 2001 From: TomaSusi Date: Tue, 7 Jul 2026 11:22:49 +0200 Subject: [PATCH] Publish versioned docs: stable at root, dev under /dev/ 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 --- .github/workflows/deploy-book.yml | 25 +++++++++++--- .github/workflows/deploy-dev.yml | 55 +++++++++++++++++++++++++++++++ docs/_config.yml | 4 +-- docs/_ext/abtem_version_footer.py | 43 ++++++++++++++++++++++-- docs/doc_requirements.txt | 18 ---------- docs/requirements.txt | 6 +--- 6 files changed, 120 insertions(+), 31 deletions(-) create mode 100644 .github/workflows/deploy-dev.yml delete mode 100644 docs/doc_requirements.txt diff --git a/.github/workflows/deploy-book.yml b/.github/workflows/deploy-book.yml index 5e0387a..f0db22c 100644 --- a/.github/workflows/deploy-book.yml +++ b/.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 diff --git a/.github/workflows/deploy-dev.yml b/.github/workflows/deploy-dev.yml new file mode 100644 index 0000000..a92f9bb --- /dev/null +++ b/.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 diff --git a/docs/_config.yml b/docs/_config.yml index 8f10c46..5045e75 100644 --- a/docs/_config.yml +++ b/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 diff --git a/docs/_ext/abtem_version_footer.py b/docs/_ext/abtem_version_footer.py index e0022a3..dd59849 100644 --- a/docs/_ext/abtem_version_footer.py +++ b/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 = ( "

Tested against " 'abTEM' - f" v{version}.

" + f" v{version}." ) + if _is_dev(): + theme_options["announcement"] = ( + "This is the development documentation, built from " + f'the latest main branch. Switch to the ' + "stable version." + ) + footer += " Development build." + else: + footer += ( + f' Also available: development version.' + ) + footer += "

" + 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 ' + ) + + 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} diff --git a/docs/doc_requirements.txt b/docs/doc_requirements.txt deleted file mode 100644 index dc9344f..0000000 --- a/docs/doc_requirements.txt +++ /dev/null @@ -1,18 +0,0 @@ -numpy -numba -pytest -scipy -h5py -matplotlib -ase -imageio -ipywidgets -docutils -jupyter-book<2 -sphinx>=5,<6 -sphinx_rtd_theme -nbsphinx -sphinx-autodoc-typehints -tqdm -psutil -pyfftw diff --git a/docs/requirements.txt b/docs/requirements.txt index 2ffc9b3..79f55b5 100644 --- a/docs/requirements.txt +++ b/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