From a7ec82f4a0591809e0ef9289d4d3686602bed50c Mon Sep 17 00:00:00 2001 From: p1c2u Date: Sun, 3 May 2026 16:31:26 +0100 Subject: [PATCH 1/2] Pagefind smoke --- .readthedocs.yaml | 22 +++++++++++++++++++++- Makefile | 14 ++++++++++++++ docs/manifest.json | 36 ++++++++++++++++++++++++++++++++++++ 3 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 docs/manifest.json diff --git a/.readthedocs.yaml b/.readthedocs.yaml index a014d4ee..158f5ba1 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,15 +1,35 @@ +# 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.14" + nodejs: "20" jobs: post_install: - pip install poetry - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with docs + # Replaces RTD's declarative Sphinx output: `make docs-publish` rebuilds + # the docs into docs/_build/html/, runs Pagefind over it, and copies + # docs/manifest.json next to the HTML. We then move docs/_build/html/* + # into $READTHEDOCS_OUTPUT/html/ so the published artifact contains both + # the manifest and the Pagefind bundle expected by the website shell. + post_build: + - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry run make docs-publish + - mkdir -p $READTHEDOCS_OUTPUT/html && cp -r docs/_build/html/* $READTHEDOCS_OUTPUT/html/ diff --git a/Makefile b/Makefile index 5ecaa795..fc46ac53 100644 --- a/Makefile +++ b/Makefile @@ -35,6 +35,20 @@ test-cleanup: test-cache-cleanup reports-cleanup cleanup: dist-cleanup test-cleanup +docs-html: + sphinx-build -b html docs docs/_build/html + +docs-pagefind: docs-html + @npx --yes pagefind --site docs/_build/html + +docs-manifest: + @cp docs/manifest.json docs/_build/html/manifest.json + +docs-publish: docs-html docs-pagefind docs-manifest + +docs-cleanup: + @rm -rf docs/_build + docker-build: @docker build --no-cache --build-arg OPENAPI_SPEC_VALIDATOR_VERSION=${VERSION} -t ${PROJECT_NAME}:${VERSION} . diff --git a/docs/manifest.json b/docs/manifest.json new file mode 100644 index 00000000..8caaac4c --- /dev/null +++ b/docs/manifest.json @@ -0,0 +1,36 @@ +{ + "manifestVersion": 1, + "projectSlug": "openapi-spec-validator", + "displayName": "openapi-spec-validator", + "themeContractVersion": 1, + "latestStableVersion": "0.7.2", + "routes": { + "publicProjectPath": "/openapi-spec-validator", + "latestDocsPath": "/openapi-spec-validator/docs/", + "versionedDocsPrefix": "/openapi-spec-validator/docs/" + }, + "versions": [ + { + "version": "0.7.2", + "label": "0.7.2", + "channel": "stable", + "isLatestStable": true, + "publicBasePath": "/openapi-spec-validator/docs/0.7.2/", + "originUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/", + "sitemapUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", + "searchBundleUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/pagefind/", + "publishedAt": "2026-04-29T00:00:00Z" + }, + { + "version": "next", + "label": "next", + "channel": "next", + "isLatestStable": false, + "publicBasePath": "/openapi-spec-validator/docs/next/", + "originUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/", + "sitemapUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", + "searchBundleUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/pagefind/", + "publishedAt": "2026-04-29T00:00:00Z" + } + ] +} From 6afe81440330811473fb0717f3f2fb947b761198 Mon Sep 17 00:00:00 2001 From: p1c2u Date: Sun, 3 May 2026 17:16:22 +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-html, docs-pagefind, docs-manifest, docs-publish, and docs-cleanup 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/html/* 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 | 1 + docs/manifest.json | 27 ++++++++------------------- 3 files changed, 36 insertions(+), 19 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 00000000..78573e5c --- /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 1eac6033..55ff6d56 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,6 +20,7 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] html_theme = "sphinx_immaterial" +html_baseurl = "https://python-openapi.org/openapi-spec-validator/docs/latest/" html_static_path = [] diff --git a/docs/manifest.json b/docs/manifest.json index 8caaac4c..dfa3a7ce 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -3,7 +3,7 @@ "projectSlug": "openapi-spec-validator", "displayName": "openapi-spec-validator", "themeContractVersion": 1, - "latestStableVersion": "0.7.2", + "latestStableVersion": "latest", "routes": { "publicProjectPath": "/openapi-spec-validator", "latestDocsPath": "/openapi-spec-validator/docs/", @@ -11,26 +11,15 @@ }, "versions": [ { - "version": "0.7.2", - "label": "0.7.2", + "version": "latest", + "label": "latest", "channel": "stable", "isLatestStable": true, - "publicBasePath": "/openapi-spec-validator/docs/0.7.2/", - "originUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/", - "sitemapUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", - "searchBundleUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/pagefind/", - "publishedAt": "2026-04-29T00:00:00Z" - }, - { - "version": "next", - "label": "next", - "channel": "next", - "isLatestStable": false, - "publicBasePath": "/openapi-spec-validator/docs/next/", - "originUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/", - "sitemapUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", - "searchBundleUrl": "https://openapi-spec-validator.readthedocs.io/en/spike-pagefind-smoke/pagefind/", - "publishedAt": "2026-04-29T00:00:00Z" + "publicBasePath": "/openapi-spec-validator/docs/latest/", + "originUrl": "https://openapi-spec-validator.readthedocs.io/en/latest/", + "sitemapUrl": "https://openapi-spec-validator.readthedocs.io/en/latest/sitemap.xml", + "searchBundleUrl": "https://openapi-spec-validator.readthedocs.io/en/latest/pagefind/", + "publishedAt": "2026-05-03T00:00:00Z" } ] }