From 815b148bc1e2579e7c7a5b3295fcc9b648e93c4e Mon Sep 17 00:00:00 2001 From: p1c2u Date: Sun, 3 May 2026 16:56:17 +0100 Subject: [PATCH 1/2] Pagefind smoke --- .readthedocs.yaml | 22 +++++++++++++++++++++- Makefile | 8 ++++++++ docs/manifest.json | 25 +++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/manifest.json diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 98d4447..29ad297 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,14 +1,26 @@ +# Read the Docs configuration file +# https://docs.readthedocs.io/en/stable/config-file/v2.html +# +# Pipeline: builds the docs (Sphinx + sphinx-immaterial), then runs Pagefind +# over the output and copies docs/manifest.json next to it. The published +# artifact is consumed by the python-openapi.org website shell, which proxies +# docs paths from the shell origin to RTD and merges the per-project Pagefind +# bundles in the browser at search time. See ../web/specs/001-openapi-website +# for the website plan and the docs-theme-contract.md. version: 2 sphinx: configuration: docs/conf.py -formats: all +# HTML only — the website shell consumes HTML + manifest + Pagefind. PDF/ePub +# builds are not needed for the integration. +formats: [] build: os: ubuntu-24.04 tools: python: "3.10" + nodejs: "20" jobs: post_create_environment: - pip install "poetry==2.1.1" @@ -16,3 +28,11 @@ build: post_install: - poetry install --with docs --no-interaction --no-ansi - python -m pip install --no-cache-dir "sphinx-immaterial>=0.11,<0.14" + # Replaces RTD's declarative Sphinx output: `make docs-publish` rebuilds + # the docs into docs/_build/, runs Pagefind over it, and copies + # docs/manifest.json next to the HTML. We then move docs/_build/* into + # $READTHEDOCS_OUTPUT/html/ so the published artifact contains both the + # manifest and the Pagefind bundle expected by the website shell. + post_build: + - poetry run make docs-publish + - mkdir -p $READTHEDOCS_OUTPUT/html && cp -r docs/_build/* $READTHEDOCS_OUTPUT/html/ diff --git a/Makefile b/Makefile index 771c6c5..1f5d7cb 100644 --- a/Makefile +++ b/Makefile @@ -34,6 +34,14 @@ test-cleanup: test-cache-cleanup reports-cleanup docs-html: sphinx-build -b html docs docs/_build +docs-pagefind: docs-html + @npx --yes pagefind --site docs/_build + +docs-manifest: + @cp docs/manifest.json docs/_build/manifest.json + +docs-publish: docs-html docs-pagefind docs-manifest + docs-cleanup: @rm -rf docs/_build diff --git a/docs/manifest.json b/docs/manifest.json new file mode 100644 index 0000000..d371321 --- /dev/null +++ b/docs/manifest.json @@ -0,0 +1,25 @@ +{ + "manifestVersion": 1, + "projectSlug": "openapi-schema-validator", + "displayName": "openapi-schema-validator", + "themeContractVersion": 1, + "latestStableVersion": "0.6.3", + "routes": { + "publicProjectPath": "/openapi-schema-validator", + "latestDocsPath": "/openapi-schema-validator/docs/", + "versionedDocsPrefix": "/openapi-schema-validator/docs/" + }, + "versions": [ + { + "version": "0.6.3", + "label": "0.6.3", + "channel": "stable", + "isLatestStable": true, + "publicBasePath": "/openapi-schema-validator/docs/0.6.3/", + "originUrl": "https://openapi-schema-validator.readthedocs.io/en/spike-pagefind-smoke/", + "sitemapUrl": "https://openapi-schema-validator.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", + "searchBundleUrl": "https://openapi-schema-validator.readthedocs.io/en/spike-pagefind-smoke/pagefind/", + "publishedAt": "2026-04-29T00:00:00Z" + } + ] +} From 743fbf3dd6e9b2e05053f26375f47711c06e2515 Mon Sep 17 00:00:00 2001 From: p1c2u Date: Sun, 3 May 2026 17:16:23 +0100 Subject: [PATCH 2/2] Add docs theme override, manifest, and Pagefind pipeline for python-openapi.org Adds the publishing-pipeline pieces required by the unified python-openapi.org website shell: - docs/_templates/layout.html: Sphinx layout override that injects the shared ecosystem banner and footer per docs-theme-contract.md - docs/manifest.json: the manifest the shell consumes to resolve versions and the Pagefind bundle URL - Makefile: docs-pagefind, docs-manifest, and docs-publish targets used by the docs publishing pipeline - .readthedocs.yaml: nodejs added under tools, post_build hook that runs `make docs-publish` and copies docs/_build/* into the RTD output, so each published build also exposes /pagefind/ and /manifest.json next to the HTML Co-Authored-By: Claude Opus 4.7 --- docs/_templates/layout.html | 27 +++++++++++++++++++++++++++ docs/conf.py | 3 +++ docs/manifest.json | 16 ++++++++-------- 3 files changed, 38 insertions(+), 8 deletions(-) create mode 100644 docs/_templates/layout.html diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html new file mode 100644 index 0000000..b1dd683 --- /dev/null +++ b/docs/_templates/layout.html @@ -0,0 +1,27 @@ +{# Shell-aware layout override for the Python OpenAPI website. #} +{# Theme contract: docs-theme-contract.md (themeContractVersion 1). #} +{% extends "!layout.html" %} + +{% block extrahead %} + {{ super() }} + + + +{% endblock %} + +{% block header %} + + {{ super() }} +{% endblock %} + +{% block footer %} + {{ super() }} +

+ Part of the Python OpenAPI. +

+{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index f94242d..be32321 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,6 +39,9 @@ def _read_project_version() -> str: exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] html_theme = "sphinx_immaterial" +html_baseurl = ( + "https://python-openapi.org/openapi-schema-validator/docs/latest/" +) html_static_path = [] diff --git a/docs/manifest.json b/docs/manifest.json index d371321..3e572dd 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -3,7 +3,7 @@ "projectSlug": "openapi-schema-validator", "displayName": "openapi-schema-validator", "themeContractVersion": 1, - "latestStableVersion": "0.6.3", + "latestStableVersion": "latest", "routes": { "publicProjectPath": "/openapi-schema-validator", "latestDocsPath": "/openapi-schema-validator/docs/", @@ -11,15 +11,15 @@ }, "versions": [ { - "version": "0.6.3", - "label": "0.6.3", + "version": "latest", + "label": "latest", "channel": "stable", "isLatestStable": true, - "publicBasePath": "/openapi-schema-validator/docs/0.6.3/", - "originUrl": "https://openapi-schema-validator.readthedocs.io/en/spike-pagefind-smoke/", - "sitemapUrl": "https://openapi-schema-validator.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", - "searchBundleUrl": "https://openapi-schema-validator.readthedocs.io/en/spike-pagefind-smoke/pagefind/", - "publishedAt": "2026-04-29T00:00:00Z" + "publicBasePath": "/openapi-schema-validator/docs/latest/", + "originUrl": "https://openapi-schema-validator.readthedocs.io/en/latest/", + "sitemapUrl": "https://openapi-schema-validator.readthedocs.io/en/latest/sitemap.xml", + "searchBundleUrl": "https://openapi-schema-validator.readthedocs.io/en/latest/pagefind/", + "publishedAt": "2026-05-03T00:00:00Z" } ] }