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.
Let’s begin writing a simple Dockerfile for Sphinx:
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:
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:
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):
After answering some questions about my project, the command generates some files. I’ve moved the autogenerated
index.rst in the
/etc/Sphinx/source folder in the container:
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.