Website integration

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

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

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

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 = []
 

docs/manifest.json

@@ -0,0 +1,25 @@
+{
+  "manifestVersion": 1,
+  "projectSlug": "openapi-spec-validator",
+  "displayName": "openapi-spec-validator",
+  "themeContractVersion": 1,
+  "latestStableVersion": "latest",
+  "routes": {
+    "publicProjectPath": "/openapi-spec-validator",
+    "latestDocsPath": "/openapi-spec-validator/docs/",
+    "versionedDocsPrefix": "/openapi-spec-validator/docs/"
+  },
+  "versions": [
+    {
+      "version": "latest",
+      "label": "latest",
+      "channel": "stable",
+      "isLatestStable": true,
+      "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"
+    }
+  ]
+}