From 73c012bbe986cdb9c73072c2ac0ea1b497cd0b47 Mon Sep 17 00:00:00 2001 From: Rob Redpath Date: Mon, 1 Jun 2026 11:59:32 +0100 Subject: [PATCH 1/3] chore: migrate to shared conf format from iati-docs-base --- .readthedocs.yaml | 6 ++++-- .vscode/launch.json | 3 ++- docs/conf.py | 41 +++++++++++++++++++++++++++++++++-------- docs/project_info.py | 23 +++++++++++++++++++++++ requirements.in | 3 ++- requirements.txt | 35 +++++++++++++++++++++++++++-------- requirements_dev.txt | 37 +++++++++++++++++++++++++++++-------- 7 files changed, 120 insertions(+), 28 deletions(-) create mode 100644 docs/project_info.py diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9633304..ea0be75 100644 --- a/.readthedocs.yaml +++ b/.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: diff --git a/.vscode/launch.json b/.vscode/launch.json index 53494f2..9ed20c2 100644 --- a/.vscode/launch.json +++ b/.vscode/launch.json @@ -7,10 +7,11 @@ "request": "launch", "module": "sphinx_autobuild", "args": [ + "-b", "dirhtml", "docs", "docs/_build/html" ], "justMyCode": false } ] -} \ No newline at end of file +} diff --git a/docs/conf.py b/docs/conf.py index 3ea24a5..658484d 100644 --- a/docs/conf.py +++ b/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, diff --git a/docs/project_info.py b/docs/project_info.py new file mode 100644 index 0000000..647f1a2 --- /dev/null +++ b/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 (for "Edit on GitHub" links) +github_repository = "https://github.com/IATI/cdfd-docs" + +# Supported languages for the documentation +languages = ["en", "fr", "es"] + +redoc = [] diff --git a/requirements.in b/requirements.in index 75920c7..0bae826 100644 --- a/requirements.in +++ b/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 \ No newline at end of file +iati-sphinx-theme diff --git a/requirements.txt b/requirements.txt index 133559f..d9c3b7d 100644 --- a/requirements.txt +++ b/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 diff --git a/requirements_dev.txt b/requirements_dev.txt index bd00afc..6907595 100644 --- a/requirements_dev.txt +++ b/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 From 0c474fa4d7cffb6321b1e8695871f9fa7af444da Mon Sep 17 00:00:00 2001 From: Rob Redpath Date: Mon, 1 Jun 2026 14:31:40 +0100 Subject: [PATCH 2/3] docs: fix github_repository comment to match actual theme behaviour --- docs/project_info.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/project_info.py b/docs/project_info.py index 647f1a2..ac88078 100644 --- a/docs/project_info.py +++ b/docs/project_info.py @@ -14,7 +14,7 @@ # Eyebrow text: the smaller text that appears directly above the website title eyebrow_text = "IATI Tools: Documentation" -# GitHub repository URL (for "Edit on GitHub" links) +# 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 From 23925afd2ea8aef44a92ba0687b51f5c11833163 Mon Sep 17 00:00:00 2001 From: Rob Redpath Date: Mon, 1 Jun 2026 14:56:44 +0100 Subject: [PATCH 3/3] bugfix: hide non-en languages until we have translations --- docs/project_info.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/project_info.py b/docs/project_info.py index ac88078..b5e28f9 100644 --- a/docs/project_info.py +++ b/docs/project_info.py @@ -18,6 +18,6 @@ github_repository = "https://github.com/IATI/cdfd-docs" # Supported languages for the documentation -languages = ["en", "fr", "es"] +languages = ["en"] redoc = []