From c9bde48b09b076f18b76e8c0528f251d208b34ef Mon Sep 17 00:00:00 2001 From: p1c2u Date: Sun, 3 May 2026 15:06:25 +0100 Subject: [PATCH 1/2] Pagefind smoke Co-authored-by: Copilot --- .readthedocs.yaml | 4 ++++ Makefile | 8 ++++++++ docs/manifest.json | 36 ++++++++++++++++++++++++++++++++++++ 3 files changed, 48 insertions(+) create mode 100644 docs/manifest.json diff --git a/.readthedocs.yaml b/.readthedocs.yaml index fe7c6754..00fd3182 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -13,6 +13,7 @@ build: os: ubuntu-24.04 tools: python: "3.12" + nodejs: "20" jobs: post_system_dependencies: - asdf plugin-add poetry @@ -20,3 +21,6 @@ build: - asdf global poetry 2.2.1 post_install: - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --no-interaction --with docs + post_build: + - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry run make docs-publish + - mkdir -p $READTHEDOCS_OUTPUT/html && cp -r docs_build/* $READTHEDOCS_OUTPUT/html/ diff --git a/Makefile b/Makefile index 56da44fa..ddf12d5b 100644 --- a/Makefile +++ b/Makefile @@ -34,6 +34,14 @@ test-cleanup: test-cache-cleanup reports-cleanup docs-html: python -m mkdocs build --clean --site-dir docs_build --config-file mkdocs.yml +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 00000000..fc4f2ee2 --- /dev/null +++ b/docs/manifest.json @@ -0,0 +1,36 @@ +{ + "manifestVersion": 1, + "projectSlug": "openapi-core", + "displayName": "openapi-core", + "themeContractVersion": 1, + "latestStableVersion": "0.23.1", + "routes": { + "publicProjectPath": "/openapi-core", + "latestDocsPath": "/openapi-core/docs/", + "versionedDocsPrefix": "/openapi-core/docs/" + }, + "versions": [ + { + "version": "0.23.1", + "label": "0.23.1", + "channel": "stable", + "isLatestStable": true, + "publicBasePath": "/openapi-core/docs/0.23.1/", + "originUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/", + "sitemapUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", + "searchBundleUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/pagefind/", + "publishedAt": "2026-04-29T00:00:00Z" + }, + { + "version": "next", + "label": "next", + "channel": "next", + "isLatestStable": false, + "publicBasePath": "/openapi-core/docs/next/", + "originUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/", + "sitemapUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", + "searchBundleUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/pagefind/", + "publishedAt": "2026-04-29T00:00:00Z" + } + ] +} From af674e8601bd60308c0b41431455dd865d7377f3 Mon Sep 17 00:00:00 2001 From: p1c2u Date: Sun, 3 May 2026 17:16:18 +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/overrides/main.html: MkDocs theme override that injects the shared ecosystem banner and footer per docs-theme-contract.md - mkdocs.yml: theme.custom_dir wired to docs/overrides - 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: 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 --- .github/workflows/build-docs.yml | 2 +- .readthedocs.yaml | 22 +++++++++++++++++----- docs/manifest.json | 27 ++++++++------------------- docs/overrides/main.html | 29 +++++++++++++++++++++++++++++ mkdocs.yml | 3 ++- poetry.lock | 27 +++++++++++++++------------ pyproject.toml | 2 +- 7 files changed, 73 insertions(+), 39 deletions(-) create mode 100644 docs/overrides/main.html diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index a39b13f9..0d5859be 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -15,7 +15,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v6 with: - python-version: "3.10" + python-version: "3.14" - name: Get full Python version id: full-python-version diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 00fd3182..e89df088 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -1,13 +1,20 @@ # Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details +# https://docs.readthedocs.io/en/stable/config-file/v2.html +# +# Pipeline: builds the docs (MkDocs Material), 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 -# Build documentation with Mkdocs mkdocs: - configuration: mkdocs.yml + configuration: mkdocs.yml -# Optionally build your docs in additional formats such as PDF and ePub -formats: all +# HTML only — the website shell consumes HTML + manifest + Pagefind. PDF/ePub +# builds are not supported by the current MkDocs plugin set. +formats: [] build: os: ubuntu-24.04 @@ -21,6 +28,11 @@ build: - asdf global poetry 2.2.1 post_install: - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --no-interaction --with docs + # Replaces RTD's declarative MkDocs output: `make docs-publish` rebuilds + # the docs into docs_build/, runs Pagefind into docs_build/pagefind/, and + # copies docs/manifest.json into docs_build/. 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: - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry run make docs-publish - mkdir -p $READTHEDOCS_OUTPUT/html && cp -r docs_build/* $READTHEDOCS_OUTPUT/html/ diff --git a/docs/manifest.json b/docs/manifest.json index fc4f2ee2..9012a923 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -3,7 +3,7 @@ "projectSlug": "openapi-core", "displayName": "openapi-core", "themeContractVersion": 1, - "latestStableVersion": "0.23.1", + "latestStableVersion": "latest", "routes": { "publicProjectPath": "/openapi-core", "latestDocsPath": "/openapi-core/docs/", @@ -11,26 +11,15 @@ }, "versions": [ { - "version": "0.23.1", - "label": "0.23.1", + "version": "latest", + "label": "latest", "channel": "stable", "isLatestStable": true, - "publicBasePath": "/openapi-core/docs/0.23.1/", - "originUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/", - "sitemapUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", - "searchBundleUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/pagefind/", - "publishedAt": "2026-04-29T00:00:00Z" - }, - { - "version": "next", - "label": "next", - "channel": "next", - "isLatestStable": false, - "publicBasePath": "/openapi-core/docs/next/", - "originUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/", - "sitemapUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/sitemap.xml", - "searchBundleUrl": "https://openapi-core.readthedocs.io/en/spike-pagefind-smoke/pagefind/", - "publishedAt": "2026-04-29T00:00:00Z" + "publicBasePath": "/openapi-core/docs/latest/", + "originUrl": "https://openapi-core.readthedocs.io/en/latest/", + "sitemapUrl": "https://openapi-core.readthedocs.io/en/latest/sitemap.xml", + "searchBundleUrl": "https://openapi-core.readthedocs.io/en/latest/pagefind/", + "publishedAt": "2026-05-03T00:00:00Z" } ] } diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 00000000..63e12eb6 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,29 @@ +{% extends "base.html" %} + +{# + Shell-aware override for the Python OpenAPI website. + Theme contract: docs-theme-contract.md (themeContractVersion 1). +#} + +{% block site_meta %} + {{ super() }} + + + +{% endblock %} + +{% block announce %} + +{% endblock %} + +{% block footer %} + {{ super() }} +

+ Part of the Python OpenAPI Ecosystem. +

+{% endblock %} diff --git a/mkdocs.yml b/mkdocs.yml index 56ddcd8e..c2698fd2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,8 +1,9 @@ site_name: OpenAPI-core site_description: OpenAPI for Python -site_url: https://openapi-core.readthedocs.io/ +site_url: https://python-openapi.org/openapi-core/docs/latest/ theme: name: material + custom_dir: docs/overrides icon: repo: fontawesome/brands/github-alt palette: diff --git a/poetry.lock b/poetry.lock index 17fd9d61..0690090f 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,4 +1,4 @@ -# This file is automatically @generated by Poetry 2.2.1 and should not be changed by hand. +# This file is automatically @generated by Poetry 2.3.1 and should not be changed by hand. [[package]] name = "aiohappyeyeballs" @@ -223,7 +223,7 @@ files = [ {file = "anyio-3.7.1-py3-none-any.whl", hash = "sha256:91dee416e570e92c64041bd18b900d1d6fa78dff7048769ce5ac5ddad004fbb5"}, {file = "anyio-3.7.1.tar.gz", hash = "sha256:44a3c9aba0f5defa43261a8b3efb97891f2bd7d804e0e1f56419befa1adfc780"}, ] -markers = {main = "extra == \"fastapi\" or extra == \"starlette\""} +markers = {main = "extra == \"starlette\" or extra == \"fastapi\""} [package.dependencies] exceptiongroup = {version = "*", markers = "python_version < \"3.11\""} @@ -992,7 +992,7 @@ files = [ {file = "exceptiongroup-1.1.3-py3-none-any.whl", hash = "sha256:343280667a4585d195ca1cf9cef84a4e178c4b6cf2274caef9859782b567d5e3"}, {file = "exceptiongroup-1.1.3.tar.gz", hash = "sha256:097acd85d473d75af5bb98e41b61ff7fe35efe6675e4f9370ec6ec5126d160e9"}, ] -markers = {main = "(extra == \"fastapi\" or extra == \"starlette\") and python_version < \"3.11\"", dev = "python_version < \"3.11\""} +markers = {main = "(extra == \"starlette\" or extra == \"fastapi\") and python_version < \"3.11\"", dev = "python_version < \"3.11\""} [package.extras] test = ["pytest (>=6)"] @@ -1281,19 +1281,22 @@ dev = ["flake8", "markdown", "twine", "wheel"] [[package]] name = "griffe" -version = "1.14.0" +version = "1.15.0" description = "Signatures for entire Python programs. Extract the structure, the frame, the skeleton of your project, to generate API documentation or find breaking changes in your API." optional = false -python-versions = ">=3.9" +python-versions = ">=3.10" groups = ["docs"] files = [ - {file = "griffe-1.14.0-py3-none-any.whl", hash = "sha256:0e9d52832cccf0f7188cfe585ba962d2674b241c01916d780925df34873bceb0"}, - {file = "griffe-1.14.0.tar.gz", hash = "sha256:9d2a15c1eca966d68e00517de5d69dd1bc5c9f2335ef6c1775362ba5b8651a13"}, + {file = "griffe-1.15.0-py3-none-any.whl", hash = "sha256:6f6762661949411031f5fcda9593f586e6ce8340f0ba88921a0f2ef7a81eb9a3"}, + {file = "griffe-1.15.0.tar.gz", hash = "sha256:7726e3afd6f298fbc3696e67958803e7ac843c1cfe59734b6251a40cdbfb5eea"}, ] [package.dependencies] colorama = ">=0.4" +[package.extras] +pypi = ["pip (>=24.0)", "platformdirs (>=4.2)", "wheel (>=0.42)"] + [[package]] name = "griffe-typingdoc" version = "0.3.1" @@ -1410,7 +1413,7 @@ files = [ {file = "idna-3.7-py3-none-any.whl", hash = "sha256:82fee1fc78add43492d3a1898bfa6d8a904cc97d8427f683ed8e798d07761aa0"}, {file = "idna-3.7.tar.gz", hash = "sha256:028ff3aadf0609c1fd278d8ea3089299412a7a8b9bd005dd08b9f8285bcb5cfc"}, ] -markers = {main = "extra == \"aiohttp\" or extra == \"fastapi\" or extra == \"starlette\" or extra == \"requests\""} +markers = {main = "extra == \"aiohttp\" or extra == \"starlette\" or extra == \"fastapi\" or extra == \"requests\""} [[package]] name = "iniconfig" @@ -1590,7 +1593,7 @@ files = [ [package.dependencies] attrs = ">=22.2.0" -jsonschema-specifications = ">=2023.03.6" +jsonschema-specifications = ">=2023.3.6" referencing = ">=0.28.4" rpds-py = ">=0.7.1" @@ -3704,7 +3707,7 @@ files = [ {file = "sniffio-1.3.0-py3-none-any.whl", hash = "sha256:eecefdce1e5bbfb7ad2eeaabf7c1eeb404d7757c379bd1f7e5cce9d8bf425384"}, {file = "sniffio-1.3.0.tar.gz", hash = "sha256:e60305c5e5d314f5389259b7f22aaa33d8f7dee49763119234af3755c55b9101"}, ] -markers = {main = "extra == \"fastapi\" or extra == \"starlette\""} +markers = {main = "extra == \"starlette\" or extra == \"fastapi\""} [[package]] name = "sqlparse" @@ -3750,7 +3753,7 @@ description = "The little ASGI library that shines." optional = true python-versions = ">=3.10" groups = ["main"] -markers = "extra == \"fastapi\" or extra == \"starlette\"" +markers = "extra == \"starlette\" or extra == \"fastapi\"" files = [ {file = "starlette-1.0.0-py3-none-any.whl", hash = "sha256:d3ec55e0bb321692d275455ddfd3df75fff145d009685eb40dc91fc66b03d38b"}, {file = "starlette-1.0.0.tar.gz", hash = "sha256:6a4beaf1f81bb472fd19ea9b918b50dc3a77a6f2e190a12954b25e6ed5eea149"}, @@ -4169,4 +4172,4 @@ werkzeug = [] [metadata] lock-version = "2.1" python-versions = "^3.10.0" -content-hash = "eb9839b032ac0b1804266342e7c7839612eb6fa83384fc3ac15c77a5e2ba8507" +content-hash = "f04bf249e048b1e6adb18c55bffa21ee6efaa4a93edca4b8327f7944da37343d" diff --git a/pyproject.toml b/pyproject.toml index 3170965d..6630efca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -113,7 +113,7 @@ mkdocs = "^1.6.1" mkdocstrings = {extras = ["python"], version = ">=0.26.1,<1.1.0"} mkdocstrings-python = ">=1.16.2,<2.0.0" mkdocs-material = "^9.5.34" -griffe = ">=1.14,<2.0" +griffe = ">=1.15,<2.0" griffe-typingdoc = ">=0.2.7,<0.4.0" [tool.pytest.ini_options]