frontend: bundle Sphinx docs locally instead of linking readthedocs

The Documentation tab pointed at jungfraujoch.readthedocs.io, which lags
behind the installed version. Build the Sphinx docs into frontend/dist/docs
and serve them at /frontend/docs so they always match the package.

- make_doc.sh: accept an output dir (default public), absolutize it, run
  from the script dir, and allow $PYTHON override
- package.json: add "docs" script building into dist/docs
- CMakeLists: run "npm run docs" in the frontend target so CPack packs the
  docs via the existing dist/ install
- App.tsx: point the Documentation DocFrame at /frontend/docs/index.html

Also clean up the Sphinx build (911 -> 0 warnings):
- fix typo myst_heading_anchor -> myst_heading_anchors so cross-doc
  #anchor links actually resolve
- suppress myst.header/myst.xref_missing (auto-generated OpenAPI client
  docs only) and the harmless sphinx_material config.cache note
- drop a dangling "---" transition at the end of CPU_DATA_ANALYSIS.md
- add REPOSITORIES and the generated python_client model pages to toctrees

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CMakeLists.txt

@@ -195,6 +195,7 @@ IF (NOT JFJOCH_WRITER_ONLY)
             COMMAND npm ci
             COMMAND npm run build
             COMMAND npm run redocly
+            COMMAND npm run docs            # bundle Sphinx docs into dist/docs (served at /frontend/docs)
             WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/frontend)
     ADD_CUSTOM_TARGET(frontend DEPENDS frontend/dist/index.html)
 

docs/CPU_DATA_ANALYSIS.md

@@ -609,5 +609,3 @@ Numerical quadrature over a scaled intensity variable is used to compute posteri
 - **Space-group symmetry** beyond centering absences is not necessarily enforced during prediction/integration unless the space group is supplied and used downstream.
 - **Resolution masking and ice rings** are controllable; including ice-ring spots in indexing can improve robustness for some samples but may bias refinement in others.
 - **Rotation vs still modes** differ substantially in prediction and scaling because partiality is angle-driven in rotation data and excitation-error-driven in still data.
-
----

docs/conf.py

@@ -29,7 +29,15 @@ myst_enable_extensions = [
     'amsmath',
 ]
 
-myst_heading_anchor = 3
+myst_heading_anchors = 3
+
+# The OpenAPI Python-client pages under docs/python_client/ are generated by the
+# openapi-generator and contain header-level jumps and intra-page anchors that MyST
+# cannot resolve. We do not hand-edit generated files, so silence that noise here;
+# the hand-written docs are anchor-clean once myst_heading_anchors is set above.
+# 'config.cache' fires only because the sphinx_material theme stores a function in
+# html_context, which is harmless for our single-shot builds.
+suppress_warnings = ['myst.header', 'myst.xref_missing', 'config.cache']
 
 # Render LaTeX-style math nicely in HTML and support AMS-style equation numbering.
 mathjax3_config = {

docs/index.rst

@@ -22,6 +22,7 @@ Jungfraujoch is distributed under the GPLv3 license.
    SOFTWARE
    VERSIONING
    DEPLOYMENT
+   REPOSITORIES
    CHANGELOG
 
 .. toctree::
@@ -67,4 +68,13 @@ Jungfraujoch is distributed under the GPLv3 license.
    :caption: OpenAPI Python client
 
    python_client/README
-   python_client/docs/DefaultApi
+   python_client/docs/DefaultApi
+
+.. The remaining python_client/docs/*.md pages are generated per-model reference
+   files linked from the client README/DefaultApi; include them in a hidden glob
+   toctree so they are built without each one warning about being orphaned.
+.. toctree::
+   :hidden:
+   :glob:
+
+   python_client/docs/*

frontend/package.json

@@ -33,6 +33,7 @@
     "build": "tsc && vite build",
     "serve": "vite preview",
     "redocly": "redocly build-docs ../broker/jfjoch_api.yaml --output=dist/openapi.html",
+    "docs": "bash ../make_doc.sh dist/docs",
     "redocly4broker": "redocly build-docs ../broker/jfjoch_api.yaml --output=../broker/redoc-static.html",
     "openapi": "openapi-ts"
   },

frontend/src/App.tsx

@@ -181,7 +181,7 @@ function App() {
                 <DocFrame title="API reference" src="/frontend/openapi.html"/>
             )},
             { id: 'documentation', label: 'Documentation', icon: <MenuBookIcon/>, render: () => (
-                <DocFrame title="Documentation" src="https://jungfraujoch.readthedocs.io/"/>
+                <DocFrame title="Documentation" src="/frontend/docs/index.html"/>
             )},
         ]},
     ];

make_doc.sh

@@ -2,11 +2,30 @@
 
 set -euo pipefail
 
-python3.11 -m venv tmp_venv/
+# Build the Sphinx HTML documentation.
+#
+# Usage: make_doc.sh [output_dir]
+#   output_dir   where the rendered HTML is written (default: ./public).
+#                Relative paths are resolved against the caller's working
+#                directory, so the frontend build can point this at frontend/dist/docs.
+#
+# The Python interpreter can be overridden with $PYTHON (default: python3.11).
+
+OUT="${1:-public}"
+PYTHON="${PYTHON:-python3.11}"
+
+# Resolve the output directory to an absolute path before we change directories.
+mkdir -p "$OUT"
+OUT="$(cd "$OUT" && pwd)"
+
+# Run from the repository root regardless of where the script was invoked from.
+cd "$(dirname "$0")"
+
+"$PYTHON" -m venv tmp_venv/
 source tmp_venv/bin/activate
 
 pip install -r docs/requirements.txt
 
-sphinx-build -b html docs public
+sphinx-build -b html docs "$OUT"
 
 rm -rf tmp_venv/