GOV.UK Tech Docs Sphinx Theme¶

A Sphinx theme to replicate the GOV.UK Tech Docs Template.

!WarningWhere this documentation refers to the root folder we mean where this README.md is located.

Getting started¶

The source code for this Sphinx theme is available at https://github.com/ukgovdatascience/govuk-tech-docs-sphinx-theme. You can use this for your own Sphinx documentation by following the steps below.

Install the package¶

The latest released version can be installed from the Python Package Index (PyPI):

pip install govuk-tech-docs-sphinx-theme

Amend your Sphinx `conf.py` configuration file¶

To use this Sphinx theme, modify your Sphinx conf.py configuration file as follows:

Add the theme in the list of extensions:

extensions = ["govuk_tech_docs_sphinx_theme"]

Make sure the author, and project variables reflect your organisation name, and project
Set html_theme = "govuk_tech_docs_sphinx_theme"

Set the html_context dictionary as follows:

html_context = {
    "github_url": None,                  # if using GitHub, set to the URL of your repository as a string
    "gitlab_url": None,                  # if using GitLab, set to the URL of your repository as a string
    "conf_py_path": "docs/",             # assuming your Sphinx folder is called `docs`
    "version": "main",                   # assuming `main` is your repository's default branch
    "accessibility": "accessibility.md"  # assuming your accessibility statement is at `docs/accessibility.md`
}

Set the html_theme_options dictionary as follows:

html_theme_options = {
    "organisation": "",  # replace with your organisation's abbreviation (ideally) or name - long text may not look nice
    "phase": ""          # replace with an Agile project phase - see https://www.gov.uk/service-manual/agile-delivery
}

Note, not all Sphinx configuration settings are currently supported by this theme — feel free to contribute to support other settings!

Add an accessibility statement¶

All public sector bodies have to meet the 2018 accessibility regulations unless exempt.

To add an accessibility statement, create a blank Markdown file in the root of your Sphinx folder called accessibility.md. This folder is the same location as your Sphinx conf.py configuration file. Add the following header to your new Markdown file:

---
orphan: true
---
# Accessibility statement

followed by your accesibility statement. Guidance on how to write an accessibility statement can be found on GOV.UK.

Next, in your Sphinx conf.py file, check that the html_context variable has this file referenced, i.e.:

html_context = {
    ...,
    "accessibility": "accessibility.md",
    ...
}

Apply the theme’s components¶

This theme should be compatible with most ReStructuredText syntax, and also includes components from the GOV.UK Design System. See the example components page for further details.

If you are using MyST to build Sphinx documentation using Markdown, see the equivalent Markdown components page.

Troubleshooting¶

If you have difficulties with this theme, please raise an issue or contact us to report a problem.

Licence¶

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation. Additional third-party component licences are stated in the LICENSE file. The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.

Contributing¶

If you want to help us build, and improve govuk-tech-docs-sphinx-theme, view our contributing guidelines.

Acknowledgements¶

This project structure is based on the govcookiecutter template project.