Integrating GOV.UK Tech Docs Sphinx Theme with Sphinx, Docker, and FastAPI

If you’re looking to create professional and user-friendly documentation for your organization, the GOV.UK Tech Docs Sphinx Theme is a great choice. In this article, we’ll explore how you can integrate the theme with Sphinx, Docker, and FastAPI to streamline the documentation process.

Prerequisites

Before we begin, make sure you have the following installed on your system:

• Python
• Sphinx
• Docker
• FastAPI

Step 1: Install the GOV.UK Tech Docs Sphinx Theme

To get started, install the GOV.UK Tech Docs Sphinx Theme using pip:

#shell
pip install govuk-tech-docs-sphinx-theme

Step 2: Modify your Sphinx conf.py configuration file

Open your Sphinx conf.py file and make the following modifications:

1. Add the theme to the list of extensions:

#python
extensions = ["govuk_tech_docs_sphinx_theme"]

2. Update the author and project variables to reflect your organization name and project.

3. Set the html_theme variable to “govuktechdocssphinxtheme”.

4. Add the following dictionary to the html_context variable:

#python
html_context = {
   "github_url": None,
   "gitlab_url": None,
   "conf_py_path": "docs/",
   "version": "main",
   "accessibility": "accessibility.md"
}

5. Set the html_theme_options dictionary as follows:

#python
html_theme_options = {
   "organisation": "",
   "phase": ""
}

Step 3: Add an accessibility statement

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

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

Write your accessibility statement below the header.

Finally, update the html_context variable in your Sphinx conf.py file to reference the accessibility.md file:

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

Step 4: Apply the theme’s components

The GOV.UK Tech Docs Sphinx Theme is compatible with most ReStructuredText syntax and includes components from the GOV.UK Design System. You can use these components to enhance the appearance and functionality of your documentation.

Step 5: Build your documentation

With the theme and configurations in place, you’re ready to build your documentation. Use the Sphinx command to build the HTML output:

#bash
sphinx-build -b html source/ build/

Step 6: Dockerize your documentation

To make your documentation easily accessible and shareable, you can Dockerize it. Create a Dockerfile file in the root folder of your documentation and add the following content:

#dockerfile
# Use an official Python runtime as the base image
FROM python:3.9-slim

# Set the working directory
WORKDIR /app

# Copy the Sphinx documentation files to the container
COPY ./build /app

# Expose the relevant port
EXPOSE 8000

# Install any necessary dependencies
RUN pip install -r requirements.txt

# Set the default command to run when the container starts
CMD ["sphinx-autobuild", "-H", "0.0.0.0", "--port", "8000", "source/", "build/"]

Build the Docker image:

#bash
docker build -t my-docs .

Run the Docker container:

#bash
docker run -p 8000:8000 my-docs

Now you can access your documentation by navigating to http://localhost:8000 in your web browser.

Step 7: Integrate with FastAPI

If you want to serve your documentation using a FastAPI server, you can easily integrate the GOV.UK Tech Docs Sphinx Theme into your FastAPI application. Here’s an example FastAPI route:

#python
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

app.mount("/docs", StaticFiles(directory="build", html=True), name="static")

@app.get("/")
async def root():
    return {"message": "Hello, World!"}

In this example, the documentation is served at the /docs endpoint.

Conclusion

Integrating the GOV.UK Tech Docs Sphinx Theme with Sphinx, Docker, and FastAPI allows you to create professional and user-friendly documentation for your organization. By following the steps outlined in this article, you can easily set up and customize your documentation to meet your specific needs. Start documenting your projects with style today!

Remember, the theme supports many other settings and customizations, so feel free to explore the documentation and contribute to its development to make it even better.

Happy documenting!