A Sphinx theme to replicate the GOV.UK Tech Docs Template.
Where this documentation refers to the root folder we mean where this README.md is located.
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.
The latest released version can be installed from the Python Package Index (PyPI):
pip install govuk-tech-docs-sphinx-theme
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
, andproject
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!
With the Sphinx autodoc extension, you may find headers do not fit the content that
follows. This [fails the WCAG 2.1 success criterion 2.4.6 Headings and
Labels][wcag-2.1-2.4.6].
To resolve this, copy the entire `docs/_template` folder from this repository into
your Sphinx folder, and ensure your `conf.py` file contains:
```python
templates_path = ["_templates"]
```
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",
...
}
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.
If you have difficulties with this theme, please raise an issue or contact us to report a problem.
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.
This project structure is based on the govcookiecutter
template
project.