Document your project adding Sphinx to docker-compose.yml

I strongly believe that a web application project has to be thoroughly documented. And that’s more important for larger and longer project, where developers come and go in an unstoppable turnover that risks to slow down the project. A documentation is the only chance for new developers to become rapidly productive.

But how we, as developers, can document a project? What tools exist out there that can facilitate this task? Well, there are dozens of tools. One of them is Sphinx, the Python Documentation Generator. This library can be used to document everything you want. You can think it as a static site generator, like Jekyll, Hugo or Gatsby, but more oriented to technical documentation. You can host it somewhere, like on the Read The Docs, or keep it locally. In this article I will explain how to use it locally with a project already using Docker Compose.

The Dockerfile

Let’s begin writing a simple Dockerfile for Sphinx:

1
2
3
4
5
6
7
8
9

FROM alpine:latest
WORKDIR /etc/
RUN mkdir -p /etc/Sphinx/build

RUN apk add --no-cache python3 make git
RUN pip3 install git+https://github.com/sphinx-doc/sphinx && \
    pip3 install sphinx-autobuild

CMD sphinx-autobuild -b html --host 0.0.0.0 --port 80 /etc/Sphinx/source /etc/Sphinx/build

Here, after using the latest Alpine image and creating some folders, I install some dependencies (python3, make, git); after that, I install sphinx and its autobuild. The Sphinx-autobuild project automatically rebuild the documentation after a change in the documentation folder is detected, and it works like a charm also with Docker. With its livereload web server, this library serves also the documentation web page, allowing you to access to the documentation with a browser visiting a URL like http://localhost:8100.

The docker-compose.yml file

Let’s add now a service to the docker-compose.yml already used in the application project:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

version: "3"

# ...
services:
  # ...
  service_doc:
    container_name: service_doc
    build: docker/doc
    volumes:
      - ./doc:/etc/Sphinx/source
    ports:
      - 8100:80
# ...

The folder structure of the project is something like:

.
├── doc
├── docker
│   └── doc
│       └── Dockerfile
└── docker-compose.yml

I’ve defined a volume in the folder ./doc, where there will be the documentation folders and files. The Sphinx Dockerfile presented above is in the folder ./docker/doc and the docker-compose.yml is in the root folder. The URL to use to visit the documentation is http://localhost:8100.

The Sphinx quickstart

I can now run the command:

1

docker-compose up -d

With this command, I’ve created a container with Sphinx. To continue, I have to create a configuration file, conf.py, in the folder ./doc. To do that, I’ve run the following command in the container (after running docker-compose exec service_doc /bin/sh):

1

sphinx-quickstart

After answering some questions about my project, the command generates some files. I’ve moved the autogenerated conf.py and index.rst in the /etc/Sphinx/source folder in the container:

1
2

mv conf.py /etc/Sphinx/source
mv index.rst /etc/Sphinx/source

Writing the documentation using Sphinx

We can now access the (empty) documentation at http://localhost:8100. If we try changing the index.rst file, after some seconds the browser auto refresh to show the updated documentation. Following the Sphinx documentation site you can now document your project using Sphinx.