Sphinx docs in Docker

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. It is also the technology that ReadTheDocs uses to build their documentation. This image helps you get started with sphinx without installing any dependencies on your computer. The only prerequirement is Docker.

Installation

The image is published on docker hub named kanisterio/sphinx.

New documentation

For new documentation create a folder for the documentation

mkdir docs

Then run the following docker command

docker run -d  -v $PWD:/repo -p 8000:8000 kanisterio/sphinx

This creates a docker container that mounts the docs directory to /docs (where the documentation is expected to be). Use docker ps to find the ID of the newly created container. Then initiate the documentation with the following command (replace 92 with the id of your container)

docker exec -it 92 sphinx-quickstart

Once the setup is done, restart the sphinx container

docker container restart 92

Open a browser and navigate to localhost:8000.

Existing documentation

Simply run

docker run -d  -v /path/to/docs:/repo/docs -p 8000:8000 kanisterio/sphinx

Open a browser and navigate to localhost:8000.

Read the docs theme

The image is prepared with the read the docs theme. In order to use it, follow the configuration instructions here:

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]