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 <noreply@anthropic.com>

Author: p1c2u

.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

.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/

docs/manifest.json

@@ -3,34 +3,23 @@
   "projectSlug": "openapi-core",
   "displayName": "openapi-core",
   "themeContractVersion": 1,
-  "latestStableVersion": "0.23.1",
+  "latestStableVersion": "latest",
   "routes": {
     "publicProjectPath": "/openapi-core",
     "latestDocsPath": "/openapi-core/docs/",
     "versionedDocsPrefix": "/openapi-core/docs/"
   },
   "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"
     }
   ]
 }

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() }}
+  <meta name="ecosystem-shell" content="Python OpenAPI Ecosystem" />
+  <meta name="ecosystem-project" content="openapi-core" />
+  <meta data-theme-contract-version="1" />
+{% endblock %}
+
+{% block announce %}
+  <aside class="ecosystem-shell-banner" aria-label="Python OpenAPI Ecosystem">
+    <a class="ecosystem-home" href="/" data-ecosystem-home="true">
+      ← Back to the Python OpenAPI
+    </a>
+    <span class="ecosystem-project-label" aria-current="page">openapi-core</span>
+  </aside>
+{% endblock %}
+
+{% block footer %}
+  {{ super() }}
+  <p class="ecosystem-footer-note" data-theme-contract-version="1">
+    Part of the <a href="/" class="ecosystem-home">Python OpenAPI Ecosystem</a>.
+  </p>
+{% endblock %}

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: