From 4395fe1b955c37040d0a7e742dc93df9ebb1be2e Mon Sep 17 00:00:00 2001 From: IsabelBirds <44876111+IsabelBirds@users.noreply.github.com> Date: Tue, 18 Nov 2025 14:09:17 +0000 Subject: [PATCH 1/3] simplify conf.py --- docs/conf.py | 381 ++++++--------------------------------------------- 1 file changed, 42 insertions(+), 339 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index db6fba8..54a4fb0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,365 +1,68 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- +# Configuration file for the Sphinx documentation builder. # -# IATI CDFD documentation build configuration file, -# created by sphinx-quickstart on Wed Nov 2 14:17:45 2016. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "myst_parser", - "sphinxcontrib.opendataservices", - "sphinxcontrib.jsonschema", - "sphinx.ext.todo", - "sphinx.ext.autodoc", - "sphinx_togglebutton", - "sphinx.ext.autosectionlabel", -] +import os -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] +import sphinx.application +from sphinx.locale import get_translation -source_suffix = [".rst"] +import iati_sphinx_theme -# The encoding of source files. -# -# source_encoding = 'utf-8-sig' +MESSAGE_CATALOG_NAME = "iati-sphinx-theme" +_ = get_translation(MESSAGE_CATALOG_NAME) -# The master toctree document. -master_doc = "index" +# -- 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. -# General information about the project. project = "IATI Tool: Documentation" -copyright = ( - "2024 United Nations Development Programme, on behalf of the IATI Secretariat" -) author = "IATI Secretariat" - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = "0.0" -# The full version, including alpha/beta/rc tags. -release = "0.0" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. language = "en" -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -# -# today = '' -# -# Else, today_fmt is used as the format for a strftime call. -# -# today_fmt = '%B %d, %Y' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] - -# The reST default role (used for this markup: `text`) to use for all -# documents. -# -# default_role = None - -# If true, '()' will be appended to :func: etc. cross-reference text. -# -# add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -# -# add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -# -# show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - -# A list of ignored prefixes for module index sorting. -# modindex_common_prefix = [] - -# If true, keep warnings as "system message" paragraphs in the built documents. -# keep_warnings = False - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.todo", + "sphinxcontrib.video", + "sphinxcontrib.youtube", +] -# -- Options for HTML output ---------------------------------------------- +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "iati_sphinx_theme" - -html_css_files = [ - "custom.css", -] - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -html_theme_options = { - "github_repository": "https://github.com/IATI/iati-docs-base", - "header_title_text": "Country Development Finance Data", - "project_title": "CDFD: Documentation", - "tool_nav_items": {"CDFD": "https://countrydata.iatistandard.org/"}, - "languages": ["en"], +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"), + "show_download_links": True, } -# Add any paths that contain custom themes here, relative to this directory. -# html_theme_path = [] - -# The name for this set of Sphinx documents. -# " v documentation" by default. -# -# html_title = 'IATI CDFD Docs' - -# A shorter title for the navigation bar. Default is the same as html_title. -# -# html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -# -# html_logo = None - -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -# -# html_favicon = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". +# Add any paths that contain custom static files (such as style sheets, videos, +# images) here, relative to this directory. They are copied after the builtin +# static files, so a file named "default.css" will overwrite the builtin +# "default.css". html_static_path = ["_static"] -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -# -# html_extra_path = [] - -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# -# html_last_updated_fmt = None - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# -# html_additional_pages = {} - -# If false, no module index is generated. -# -# html_domain_indices = True - -# If false, no index is generated. -# -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -# -# html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -# -# html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' -# -# html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -# -# html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -# -# html_search_scorer = 'scorer.js' - -# Output file base name for HTML help builder. -htmlhelp_basename = "sphinxdoc" - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, "sphinx.tex", "IATI CDFD Docs", "IATI Secretariat", "manual"), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# -# latex_use_parts = False - -# If true, show page references after internal links. -# -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# -# latex_appendices = [] - -# It false, will not define \strong, \code, itleref, \crossref ... but only -# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added -# packages. -# -# latex_keep_old_macro_names = True - -# If false, no module index is generated. -# -# latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(master_doc, "sphinx", "IATI CDFD Docs", [author], 1)] - -# If true, show URL addresses after external links. -# -# man_show_urls = False - +todo_include_todos = True # -- Options for Texinfo output ------------------------------------------- -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - "sphinx", - "IATI CDFD Docs", - author, - "sphinx", - "One line description of project.", - "Miscellaneous", - ), +locale_dirs = [ + "locale", + os.path.join(os.path.dirname(iati_sphinx_theme.__file__), "locale"), ] -# Documents to append as an appendix to all manuals. -# -# texinfo_appendices = [] - -# If false, no module index is generated. -# -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# -# texinfo_no_detailmenu = False - - -locale_dirs = ["locale/"] # path is example but recommended. -gettext_compact = False # optional. -togglebutton_hint = "" +def setup(app: sphinx.application.Sphinx) -> None: + locale_path = os.path.join(os.path.abspath(os.path.dirname(__file__)), "locale") + app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_path) From 27194ceb2fac48f4b673dc17464b685193d95bf7 Mon Sep 17 00:00:00 2001 From: IsabelBirds <44876111+IsabelBirds@users.noreply.github.com> Date: Tue, 18 Nov 2025 14:12:54 +0000 Subject: [PATCH 2/3] add reqs for video --- requirements.in | 4 +++- requirements.txt | 19 +++++++++++++------ requirements_dev.txt | 17 ++++++++++++----- 3 files changed, 28 insertions(+), 12 deletions(-) diff --git a/requirements.in b/requirements.in index 24dc5c2..75920c7 100644 --- a/requirements.in +++ b/requirements.in @@ -1,5 +1,7 @@ sphinx sphinx-togglebutton sphinxcontrib-opendataservices +sphinxcontrib-video +sphinxcontrib-youtube sphinx-intl -iati-sphinx-theme +iati-sphinx-theme \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 3983375..ca23cfe 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,7 +6,7 @@ # alabaster==1.0.0 # via sphinx -attrs==25.4.0 +attrs==25.3.0 # via referencing babel==2.17.0 # via @@ -14,7 +14,7 @@ babel==2.17.0 # sphinx-intl certifi==2025.10.5 # via requests -charset-normalizer==3.4.4 +charset-normalizer==3.4.3 # via requests click==8.3.0 # via sphinx-intl @@ -25,9 +25,9 @@ docutils==0.21.2 # sphinx-togglebutton # sphinxcontrib-opendataservices # sphinxcontrib-opendataservices-jsonschema -iati-sphinx-theme==3.1.1 +iati-sphinx-theme==3.1.0 # via -r requirements.in -idna==3.11 +idna==3.10 # via requests imagesize==1.4.1 # via sphinx @@ -67,12 +67,13 @@ pygments==2.19.2 # via sphinx pyyaml==6.0.3 # via myst-parser -referencing==0.37.0 +referencing==0.36.2 # via sphinxcontrib-opendataservices-jsonschema requests==2.32.5 # via # jscc # sphinx + # sphinxcontrib-youtube roman-numerals-py==3.1.0 # via sphinx rpds-py==0.27.1 @@ -86,6 +87,8 @@ sphinx==8.2.3 # sphinx-intl # sphinx-togglebutton # sphinxcontrib-opendataservices + # sphinxcontrib-video + # sphinxcontrib-youtube sphinx-intl==2.3.2 # via -r requirements.in sphinx-togglebutton==0.3.2 @@ -106,10 +109,14 @@ sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 # via sphinx +sphinxcontrib-video==0.4.1 + # via -r requirements.in +sphinxcontrib-youtube==1.4.1 + # via -r requirements.in urllib3==2.5.0 # via requests wheel==0.45.1 # via sphinx-togglebutton # The following packages are considered to be unsafe in a requirements file: -# setuptools +# setuptools \ No newline at end of file diff --git a/requirements_dev.txt b/requirements_dev.txt index 32e43ce..249a8bf 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -12,7 +12,7 @@ anyio==4.11.0 # via # starlette # watchfiles -attrs==25.4.0 +attrs==25.3.0 # via # -r requirements.txt # referencing @@ -27,7 +27,7 @@ certifi==2025.10.5 # via # -r requirements.txt # requests -charset-normalizer==3.4.4 +charset-normalizer==3.4.3 # via # -r requirements.txt # requests @@ -49,9 +49,9 @@ docutils==0.21.2 # sphinxcontrib-opendataservices-jsonschema h11==0.16.0 # via uvicorn -iati-sphinx-theme==3.1.1 +iati-sphinx-theme==3.1.0 # via -r requirements.txt -idna==3.11 +idna==3.10 # via # -r requirements.txt # anyio @@ -126,7 +126,7 @@ pyyaml==6.0.3 # via # -r requirements.txt # myst-parser -referencing==0.37.0 +referencing==0.36.2 # via # -r requirements.txt # sphinxcontrib-opendataservices-jsonschema @@ -135,6 +135,7 @@ requests==2.32.5 # -r requirements.txt # jscc # sphinx + # sphinxcontrib-youtube roman-numerals-py==3.1.0 # via # -r requirements.txt @@ -157,6 +158,8 @@ sphinx==8.2.3 # sphinx-intl # sphinx-togglebutton # sphinxcontrib-opendataservices + # sphinxcontrib-video + # sphinxcontrib-youtube sphinx-autobuild==2025.8.25 # via -r requirements_dev.in sphinx-intl==2.3.2 @@ -193,6 +196,10 @@ sphinxcontrib-serializinghtml==2.0.0 # via # -r requirements.txt # sphinx +sphinxcontrib-video==0.4.1 + # via -r requirements.txt +sphinxcontrib-youtube==1.4.1 + # via -r requirements.txt starlette==0.48.0 # via sphinx-autobuild urllib3==2.5.0 From fba7d438fc3c4d0e823de4a0fe43a413e0751333 Mon Sep 17 00:00:00 2001 From: IsabelBirds <44876111+IsabelBirds@users.noreply.github.com> Date: Wed, 3 Dec 2025 10:36:38 +0000 Subject: [PATCH 3/3] Fix references --- docs/data_fields.rst | 12 +++++++----- docs/example_queries.rst | 7 +++---- docs/processing.rst | 6 +++++- docs/retrieval.rst | 2 ++ 4 files changed, 17 insertions(+), 10 deletions(-) diff --git a/docs/data_fields.rst b/docs/data_fields.rst index 2b26e66..0b866c9 100644 --- a/docs/data_fields.rst +++ b/docs/data_fields.rst @@ -57,8 +57,8 @@ Depending on the detail published, this field may include the name of the organs The name used for the same organisation may vary between reporting organisations. For example, AfDB, African Development Bank, African Development Bank Group, etc. -Where organisations do not declare a :iati-reference:`provider-org` for a transaction, the logic described in the Methodology; :ref:`Provider and receiver organisations` section is followed. -For budgets, the logic described in the Methodology; :ref:`Budget Handling` section is followed. +Where organisations do not declare a :iati-reference:`provider-org` for a transaction, the logic described in the Methodology; :ref:`Provider and receiver organisations ` section is followed. +For budgets, the logic described in the Methodology; :ref:`Budget Handling ` section is followed. Provider Organisation Type @@ -72,8 +72,8 @@ Receiver Organisation The organisation receiving the specified transaction amount. Depending on the detail published, this field may include the name of the organsation, their unique organisation identifier, or both. -Where organisations do not declare a :iati-reference:`receiver-org` for a transaction, the logic described in the Methodology; :ref:`Provider and receiver organisations` section is followed. -For budgets, the logic described in the Methodology; :ref:`Budget Handling` section is followed. +Where organisations do not declare a :iati-reference:`receiver-org` for a transaction, the logic described in the Methodology; :ref:`Provider and receiver organisations ` section is followed. +For budgets, the logic described in the Methodology; :ref:`Budget Handling ` section is followed. Receiver Organisation Type =========================== @@ -106,7 +106,7 @@ Multi Country Indicates whether the activity has one or multiple recipient countries, where 1 = True and 0 = False. If it is a multi-country activity, this means that the estimated percentage to that country has been applied to the transaction / budget values. -The logic of transaction splitting is described in the Methodology; :ref:`Transaction Splitting` section. +The logic of transaction splitting is described in the Methodology; :ref:`Transaction Splitting ` section. Sector Category ================ @@ -128,6 +128,8 @@ Calendar Year ============== The year in which the transaction occurred or the year for which the budget values have been aggregated. +.. _cal quarters: + Calendar Quarter ================= This is the quarter in which the transaction occurred or the quarter for which the budget values have been aggregated. diff --git a/docs/example_queries.rst b/docs/example_queries.rst index 29cf674..482ba04 100644 --- a/docs/example_queries.rst +++ b/docs/example_queries.rst @@ -12,7 +12,7 @@ Example Queries | .. _q1: -1: How do I find organisations involved in humanitarian responses? +1: How do I find organisations involved in humanitarian responses? ------------------------------------------------------------------- A Local NGO is looking to coordinate with other organisations. They want to find a list of organisations who are supporting the humanitarian response in Lebanon. @@ -40,12 +40,11 @@ The `resulting table ` for more information. -| .. _q2: -2: What external resources were spent in 2021 Q4 in Zimbabwe? +2: What external resources were spent in 2021 Q4 in Zimbabwe? ------------------------------------------------------------------- The Ministry of Finance in Zimbabwe needs data on external inflows to the country to feed into the quarterly calculation of Balance of Payments. diff --git a/docs/processing.rst b/docs/processing.rst index 5be4f94..5538092 100644 --- a/docs/processing.rst +++ b/docs/processing.rst @@ -4,6 +4,8 @@ Data Processing This section outlines how IATI data is processed by CDFD. +.. _trans_split: + Transaction Splitting =========================== @@ -82,7 +84,7 @@ When correcting percentages for countries/regions, the following logic is used: Aggregation ============ -Once split by country/region and sector, transactions and budgets are aggregated into calendar years and :ref:`calendar quarters`. +Once split by country/region and sector, transactions and budgets are aggregated into calendar years and :ref:`calendar quarters`. Each row is the quarterly/yearly aggregation where all other data fields are the same. This means that the quarter may be split across multiple rows, such as in the multi-sector `activity `_ shown below: @@ -107,6 +109,8 @@ Budget values are converted using the closest date to the budget :iati-reference Monthly exchange rates for 169 currencies are sourced from the IMF's `International Financial Statistics `_. +.. _budgets: + Budget Handling ====================== diff --git a/docs/retrieval.rst b/docs/retrieval.rst index 2cc025d..cb96c2c 100644 --- a/docs/retrieval.rst +++ b/docs/retrieval.rst @@ -62,6 +62,8 @@ For some elements, the data can be declared at transaction or activity level. Tr | +.. _prov_rec: + Provider and receiver organisations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~