Package: govuk-tech-docs-sphinx-theme
GOV.UK Tech Docs Sphinx ThemeA 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.Getting startedThe source code for this Sphinx theme is available athttps://github.com/ukgovdatascience/govuk-tech-docs-sphinx-theme. You
can use this for your own Sphinx documentation by following the steps below.Install the packageThe latest released version can be installed from thePython Package Index
(PyPI):pipinstallgovuk-tech-docs-sphinx-themeAmend your Sphinxconf.pyconfiguration fileTo use this Sphinx theme, modify your Sphinxconf.pyconfiguration file as follows:Add the theme in the list ofextensions:extensions=["govuk_tech_docs_sphinx_theme"]Make sure theauthor, andprojectvariables reflect your organisation name, and
projectSethtml_theme = "govuk_tech_docs_sphinx_theme"Set thehtml_contextdictionary 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 thehtml_theme_optionsdictionary 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 statementWith 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 the2018 accessibility
regulationsunless exempt.To add an accessibility statement, create a blank Markdown file in the root of your
Sphinx folder calledaccessibility.md. This folder is the same location as your
Sphinxconf.pyconfiguration file. Add the following header to your new Markdown file:---orphan: true---# Accessibility statementfollowed by your accesibility statement.Guidance on how to write an accessibility
statement can be found on GOV.UK.Next, in your Sphinxconf.pyfile, check that thehtml_contextvariable has this
file referenced, i.e.:html_context={...,"accessibility":"accessibility.md",...}Apply the theme's componentsThis theme should be compatible with most ReStructuredText syntax, and also includescomponents 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
theequivalent Markdown components page.TroubleshootingIf you have difficulties with this theme,please raise an issueorcontact us to report a problem.LicenceUnless 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 theLICENSEfile. The documentation is
© Crown copyright and available under the terms of the Open Government 3.0 licence.ContributingIf you want to help us build, and improvegovuk-tech-docs-sphinx-theme, view our
contributing guidelines.AcknowledgementsThis project structure is based on thegovcookiecuttertemplate
project.