IATI Sphinx Theme#

Installation#

  1. Install the theme in your Sphinx project.

    pip install iati-sphinx-theme

  2. In your project’s conf.py set the html_theme.

    html_theme = "iati_sphinx_theme"

Configuration#

This theme has multiple options, which can be configured using the html_theme_options object in your conf.py file.

html_theme_options = {
  "github_repository": "https://github.com/organisation/repository",
  "header_title_text": "IATI Sphinx Theme",
  "header_eyebrow_text": "IATI Tools: Documentation",
  "languages": ["en", "fr", "es"],
  "plausible_domain": "example.com",
  "project_title": "IATI Sphinx Theme: Documentation",
  "tool_nav_items": {
    "IATI Tool": "https://tool.iatistandard.org/"
  },
}

There is more information on each option below.

github_repository#

This should be a link to the Github repository for the documentation site, and is used to link to the source code in the footer of the site.

header_title_text#

The title text to display in the header. Defaults to the value of project in conf.py.

header_eyebrow_text#

The text above the title in the header. Defaults to “IATI Tools: Documentation”.

languages#

A list of languages which the documentation is available in, used to populate the language switcher component. Defaults to English only.

plausible_domain#

To integrate with Plausible Analytics, add the plausible_domain option in your project’s conf.py file.

If your docs site is a subdomain for the site it is documenting, use the top level domain for cross-subdomain tracking. For example, for the Sphinx site docs.example.com, use example.com as your plausible_domain.

html_theme_options = {
  "plausible_domain": "example.com"
}

project_title#

The text to use in the breadcrumb and tool navigation components.

tool_nav_items#

Items to include in the header tool nav bar. Defaults to a single item that links back to the site’s homepage.

Custom roles#

iati-reference#

When referencing elements of the standard, use the iati-reference role. For example:

:iati-reference:`iati-activities/iati-activity/iati-identifier`

The code above will apply the following styles:

iati-activities/iati-activity/iati-identifier

Translation#

The IATI Sphinx Theme is translatable. The following languages are currently supported:

  • English (en)

  • French (fr)

  • Spanish (es)

Built-in strings#

To enable translation of built-in strings, you must add the theme to the locale_dirs list in your conf.py.

import os
import iati_sphinx_theme

local_dirs = [
  "locale",
  os.path.join(os.path.dirname(iati_sphinx_theme.__file__), "locale")
]

User-defined strings#

User-defined strings must be translated by the user of the theme. These are configured in your conf.py file under html_theme_options. In order to translate these, complete the following steps in the same location as the conf.py file:

  1. Mark strings as translatable using sphinx.locale.get_translation, usually renamed to _().

import os
from sphinx.locale import get_translation

MESSAGE_CATALOG_NAME = "iati-sphinx-theme"
_ = get_translation(MESSAGE_CATALOG_NAME)

html_theme_options = {
    "header_title_text": _("Title"),
    "tool_name": _("IATI Example Tool"),
}

def setup(app):
    locale_path = os.path.join(os.path.abspath(os.path.dirname(__file__)), "locale")
    app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_path)

  1. Extract translatable strings to locale/iati-sphinx-theme.pot.

pybabel extract conf.py -o locale/iati-sphinx-theme.pot

  1. Create or update .po files for desired languages.

# To add a new language
pybabel init -i locale/iati-sphinx-theme.pot -d locale --domain=iati-sphinx-theme -l es

# To update an existing language
pybabel update -i locale/iati-sphinx-theme.pot -d locale --domain=iati-sphinx-theme -l es

  1. Compile the .mo files. This must be done before Sphinx builds the project, for example using Read the Docs’ pre_build job, or by compiling and committing the files to version control.

pybabel compile -d locale --domain=iati-sphinx-theme

  1. Continue with your project’s usual translation workflow.