From 784cf87cc893538ba899b820d39afe7f494cd6cd Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 2 Sep 2026 08:57:35 +0200 Subject: [PATCH] docs: put the generated python-client reference behind one landing page The OpenAPI Python client owned the sidebar: DefaultApi's 128 method anchors plus the 64 hidden-glob model pages were 195 of its 256 entries, because sphinx_material's globaltoc includes hidden toctrees by default. A new PYTHON_CLIENT.md landing page carries the links and a hidden glob toctree, and globaltoc_includehidden is off, so every generated page is still built and reachable (verified: 64 model pages + DefaultApi render, zero warnings) while the sidebar drops to 61 entries. docs/review/ joins exclude_patterns so a local, gitignored review report can never again be rendered into the published site. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01EFEJG6WBQv8th4UJFNe53N --- docs/PYTHON_CLIENT.md | 23 +++++++++++++++++++++++ docs/conf.py | 8 +++++++- docs/index.rst | 17 +---------------- 3 files changed, 31 insertions(+), 17 deletions(-) create mode 100644 docs/PYTHON_CLIENT.md diff --git a/docs/PYTHON_CLIENT.md b/docs/PYTHON_CLIENT.md new file mode 100644 index 000000000..b97843528 --- /dev/null +++ b/docs/PYTHON_CLIENT.md @@ -0,0 +1,23 @@ +# OpenAPI Python client + +The broker's REST API has a generated Python client, published on PyPI as +[`jfjoch-client`](https://pypi.org/project/jfjoch-client/) and regenerated from +`broker/jfjoch_api.yaml` by `update_version.sh` — the YAML is the single source of truth +(see [OpenAPI](OPENAPI.md)). + +- [Client README](python_client/README.md) — installation, quick start, and the index of every + endpoint and model. +- [DefaultApi](python_client/docs/DefaultApi.md) — the full endpoint reference, with a generated + example per call. + +The per-model pages are generated as well and are linked from the two pages above. They are built +with the site but kept out of the navigation sidebar on purpose — sixty generated reference pages +would otherwise be most of it. + +```{toctree} +:hidden: +:glob: + +python_client/README +python_client/docs/* +``` diff --git a/docs/conf.py b/docs/conf.py index 83c96c2db..3a32284ce 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,7 +20,9 @@ extensions = [ ] templates_path = ['_templates'] -exclude_patterns = [] +# docs/review/ is gitignored working material (review reports, work plans); Sphinx renders +# whatever is on disk, so without this a local review file would become a published page. +exclude_patterns = ['review'] myst_enable_extensions = [ 'linkify', @@ -66,6 +68,10 @@ html_theme_options = { 'html_minify': True, 'css_minify': True, 'globaltoc_depth': 2, + # The generated python-client pages live in a hidden toctree on PYTHON_CLIENT.md: built and + # linked, but out of the sidebar - with the default includehidden=True they were 195 of the + # sidebar's 256 entries. + 'globaltoc_includehidden': False, # sphinx_material only knows github/gitlab/bitbucket; the repository is Gitea, so 'gitlab' is # picked purely for the icon it renders next to repo_url above. 'repo_type': 'gitlab', diff --git a/docs/index.rst b/docs/index.rst index d2f7b2d3a..e557661de 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,25 +61,10 @@ Jungfraujoch is distributed under the GPLv3 license. CPU_DATA_ANALYSIS OPENAPI OPENAPI_SPECS + PYTHON_CLIENT CBOR HDF5 IMAGE_STREAM PIXEL_MASK WEB_FRONTEND TESTS - -.. toctree:: - :maxdepth: 1 - :caption: OpenAPI Python client - - python_client/README - 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/*