chore: migrate to shared conf format from iati-docs-base

.readthedocs.yaml

@@ -20,8 +20,10 @@ sphinx:
   configuration: docs/conf.py
   builder: dirhtml
 
-# Build all formats, including PDF
-formats: all
+# Build PDF and htmlzip formats only (excluding EPUB due to todo extension compatibility)
+formats:
+  - pdf
+  - htmlzip
 
 # Optionally declare the Python requirements required to build your docs
 python:

.vscode/launch.json

@@ -7,10 +7,11 @@
             "request": "launch",
             "module": "sphinx_autobuild",
             "args": [
+                "-b", "dirhtml",
                 "docs",
                 "docs/_build/html"
             ],
             "justMyCode": false
         }
     ]
-}
+}

docs/conf.py

@@ -2,6 +2,9 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+# NOTE: This file is designed to be synced across all IATI documentation repos.
+# Project-specific settings are imported from project_info.py.
 
 import os
 
@@ -10,14 +13,34 @@
 
 import iati_sphinx_theme
 
+# Import project-specific settings
+from project_info import (
+    project,
+    tool_url,
+    nav_label,
+    eyebrow_text,
+    github_repository,
+    languages,
+    redoc,
+)
+
+# Derive nav and title from project_info. When tool_url is set, the
+# header shows two nav items: the tool itself, and a self-link to the
+# documentation. When unset, just the self-link.
+_nav_label = nav_label or project
+if tool_url:
+    tool_nav_items = {_nav_label: tool_url}
+    project_title = f"{_nav_label}: Documentation"
+else:
+    tool_nav_items = {}
+    project_title = project
+
 MESSAGE_CATALOG_NAME = "iati-sphinx-theme"
 _ = get_translation(MESSAGE_CATALOG_NAME)
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-# These are kept for compatibility but shouldn't appear anywhere on the final website.
 
-project = "IATI Tool: Documentation"
 author = "IATI Secretariat"
 language = "en"
 
@@ -26,7 +49,9 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
     "sphinx.ext.todo",
+    "sphinxcontrib.redoc",
     "sphinxcontrib.video",
     "sphinxcontrib.youtube",
 ]
@@ -39,13 +64,13 @@
 
 html_theme = "iati_sphinx_theme"
 html_theme_options = {  # See https://iati-sphinx-theme.readthedocs-hosted.com/en/latest/#configuration for additional options and info
-    "github_repository": "https://github.com/IATI/sphinx-theme",
-    "header_title_text": _("Country Development Finance Data"),
-    "header_eyebrow_text": _("IATI Documentation"),
-    "languages": ["en", "fr", "es"],
-    "project_title": _("CDFD: Documentation"),
+    "github_repository": github_repository,
+    "header_title_text": _(project),
+    "header_eyebrow_text": _(eyebrow_text),
+    "languages": languages,
+    "project_title": _(project_title),
     "show_download_links": True,
-    "tool_nav_items": {"CDFD": "https://countrydata.iatistandard.org/"},
+    "tool_nav_items": tool_nav_items,
 }
 
 # Add any paths that contain custom static files (such as style sheets, videos,

docs/project_info.py

@@ -0,0 +1,23 @@
+# Project-specific configuration for Sphinx documentation.
+# This file contains settings that vary per repository.
+# The main conf.py imports these values and can be synced across all repos.
+
+# Project name (used for titles, headers, and Sphinx internals)
+project = "Country Development Finance Data"
+
+# URL of the live tool this repo documents.
+tool_url = "https://countrydata.iatistandard.org/"
+
+# Short label used in the nav. Defaults to ``project`` when None.
+nav_label = "CDFD"
+
+# Eyebrow text: the smaller text that appears directly above the website title
+eyebrow_text = "IATI Tools: Documentation"
+
+# GitHub repository URL (used by the theme for the "Source code at GitHub" footer link)
+github_repository = "https://github.com/IATI/cdfd-docs"
+
+# Supported languages for the documentation
+languages = ["en"]
+
+redoc = []

requirements.in

@@ -1,7 +1,8 @@
 sphinx
 sphinx-togglebutton
 sphinxcontrib-opendataservices
+sphinxcontrib-redoc @ git+https://github.com/OpenDataServices/sphinxcontrib-redoc.git@main
 sphinxcontrib-video
 sphinxcontrib-youtube
 sphinx-intl
-iati-sphinx-theme
+iati-sphinx-theme

requirements.txt

@@ -7,14 +7,16 @@
 alabaster==1.0.0
     # via sphinx
 attrs==25.4.0
-    # via referencing
-babel==2.17.0
+    # via
+    #   jsonschema
+    #   referencing
+babel==2.18.0
     # via
     #   sphinx
     #   sphinx-intl
-certifi==2026.1.4
+certifi==2026.2.25
     # via requests
-charset-normalizer==3.4.4
+charset-normalizer==3.4.6
     # via requests
 click==8.3.1
     # via sphinx-intl
@@ -29,12 +31,13 @@ iati-sphinx-theme==3.1.1
     # via -r requirements.in
 idna==3.11
     # via requests
-imagesize==1.4.1
+imagesize==2.0.0
     # via sphinx
 jinja2==3.1.6
     # via
     #   myst-parser
     #   sphinx
+    #   sphinxcontrib-redoc
 jscc==0.3.0
     # via sphinxcontrib-opendataservices-jsonschema
 json-merge-patch==0.3.0
@@ -47,6 +50,10 @@ jsonref==1.1.0
     # via
     #   jscc
     #   sphinxcontrib-opendataservices-jsonschema
+jsonschema==4.26.0
+    # via sphinxcontrib-redoc
+jsonschema-specifications==2025.9.1
+    # via jsonschema
 markdown-it-py==4.0.0
     # via
     #   mdit-py-plugins
@@ -68,9 +75,14 @@ packaging==26.0
 pygments==2.19.2
     # via sphinx
 pyyaml==6.0.3
-    # via myst-parser
+    # via
+    #   myst-parser
+    #   sphinxcontrib-redoc
 referencing==0.37.0
-    # via sphinxcontrib-opendataservices-jsonschema
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+    #   sphinxcontrib-opendataservices-jsonschema
 requests==2.32.5
     # via
     #   jscc
@@ -79,7 +91,11 @@ requests==2.32.5
 roman-numerals==4.1.0
     # via sphinx
 rpds-py==0.30.0
-    # via referencing
+    # via
+    #   jsonschema
+    #   referencing
+six==1.17.0
+    # via sphinxcontrib-redoc
 snowballstemmer==3.0.1
     # via sphinx
 sphinx==9.1.0
@@ -89,6 +105,7 @@ sphinx==9.1.0
     #   sphinx-intl
     #   sphinx-togglebutton
     #   sphinxcontrib-opendataservices
+    #   sphinxcontrib-redoc
     #   sphinxcontrib-video
     #   sphinxcontrib-youtube
 sphinx-intl==2.3.2
@@ -109,6 +126,8 @@ sphinxcontrib-opendataservices-jsonschema==0.7.1
     # via sphinxcontrib-opendataservices
 sphinxcontrib-qthelp==2.0.0
     # via sphinx
+sphinxcontrib-redoc @ git+https://github.com/OpenDataServices/sphinxcontrib-redoc.git@main
+    # via -r requirements.in
 sphinxcontrib-serializinghtml==2.0.0
     # via sphinx
 sphinxcontrib-video==0.4.2

requirements_dev.txt

@@ -15,19 +15,20 @@ anyio==4.12.1
 attrs==25.4.0
     # via
     #   -r requirements.txt
+    #   jsonschema
     #   referencing
-babel==2.17.0
+babel==2.18.0
     # via
     #   -r requirements.txt
     #   sphinx
     #   sphinx-intl
-black==26.1.0
+black==26.3.1
     # via -r requirements_dev.in
-certifi==2026.1.4
+certifi==2026.2.25
     # via
     #   -r requirements.txt
     #   requests
-charset-normalizer==3.4.4
+charset-normalizer==3.4.6
     # via
     #   -r requirements.txt
     #   requests
@@ -56,7 +57,7 @@ idna==3.11
     #   -r requirements.txt
     #   anyio
     #   requests
-imagesize==1.4.1
+imagesize==2.0.0
     # via
     #   -r requirements.txt
     #   sphinx
@@ -65,6 +66,7 @@ jinja2==3.1.6
     #   -r requirements.txt
     #   myst-parser
     #   sphinx
+    #   sphinxcontrib-redoc
 jscc==0.3.0
     # via
     #   -r requirements.txt
@@ -83,6 +85,14 @@ jsonref==1.1.0
     #   -r requirements.txt
     #   jscc
     #   sphinxcontrib-opendataservices-jsonschema
+jsonschema==4.26.0
+    # via
+    #   -r requirements.txt
+    #   sphinxcontrib-redoc
+jsonschema-specifications==2025.9.1
+    # via
+    #   -r requirements.txt
+    #   jsonschema
 markdown-it-py==4.0.0
     # via
     #   -r requirements.txt
@@ -115,21 +125,24 @@ packaging==26.0
     #   wheel
 pathspec==1.0.4
     # via black
-platformdirs==4.5.1
+platformdirs==4.9.4
     # via black
 pygments==2.19.2
     # via
     #   -r requirements.txt
     #   sphinx
-pytokens==0.4.0
+pytokens==0.4.1
     # via black
 pyyaml==6.0.3
     # via
     #   -r requirements.txt
     #   myst-parser
+    #   sphinxcontrib-redoc
 referencing==0.37.0
     # via
     #   -r requirements.txt
+    #   jsonschema
+    #   jsonschema-specifications
     #   sphinxcontrib-opendataservices-jsonschema
 requests==2.32.5
     # via
@@ -144,7 +157,12 @@ roman-numerals==4.1.0
 rpds-py==0.30.0
     # via
     #   -r requirements.txt
+    #   jsonschema
     #   referencing
+six==1.17.0
+    # via
+    #   -r requirements.txt
+    #   sphinxcontrib-redoc
 snowballstemmer==3.0.1
     # via
     #   -r requirements.txt
@@ -157,6 +175,7 @@ sphinx==9.1.0
     #   sphinx-intl
     #   sphinx-togglebutton
     #   sphinxcontrib-opendataservices
+    #   sphinxcontrib-redoc
     #   sphinxcontrib-video
     #   sphinxcontrib-youtube
 sphinx-autobuild==2025.8.25
@@ -191,6 +210,8 @@ sphinxcontrib-qthelp==2.0.0
     # via
     #   -r requirements.txt
     #   sphinx
+sphinxcontrib-redoc @ git+https://github.com/OpenDataServices/sphinxcontrib-redoc.git@main
+    # via -r requirements.txt
 sphinxcontrib-serializinghtml==2.0.0
     # via
     #   -r requirements.txt
@@ -205,7 +226,7 @@ urllib3==2.6.3
     # via
     #   -r requirements.txt
     #   requests
-uvicorn==0.40.0
+uvicorn==0.42.0
     # via sphinx-autobuild
 watchfiles==1.1.1
     # via sphinx-autobuild