Sphinx Docker Image

A Docker image for Sphinx, a documentation tool written in Python.

Supported Tags and Respective Dockerfile Links

• 1.7.1, latest (Dockerfile)
• 1.7.1-latex, latex (Dockerfile.latex)

What Is Sphinx?

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation. It has excellent facilities for the documentation of software projects in a range of languages. Output formats like HTML, LaTeX, ePub, Texinfo, manual pages and plain text are supported. More than 50 extensions contributed by users are available.

How to Use This Image

Use the Image for Your Sphinx Project

First run sphinx-quickstart to set up a source directory and a configuration:

docker run -it --rm -v "$(pwd)/docs":/home/python/docs keimlink/sphinx-doc:1.7.1 sphinx-quickstart docs

Then build the HTML documentation:

docker run -it --rm -v "$(pwd)/docs":/home/python/docs keimlink/sphinx-doc:1.7.1 make -C docs html

Create a Dockerfile for Your Sphinx Project

If you want to extend the image you can create a Dockerfile for your Sphinx project. In this example sphinx-autobuild will be used to rebuild the documentation when a change is detected.

Start with a requirements file called requirements.pip:

sphinx-autobuild==0.7.1

Then create the Dockerfile:

FROM keimlink/sphinx-doc:1.7.1

COPY --chown=1000:1000 requirements.pip ./

RUN . .venv/bin/activate \
    && python -m pip install --requirement requirements.pip

EXPOSE 8000

CMD ["sphinx-autobuild", "--host", "0.0.0.0", "--port", "8000", "/home/python/docs", "/home/python/docs/_build/html"]

Now build the image and run the container:

docker build -t sphinx-autobuild .
docker run -it -p 8000:8000 --rm -v "$(pwd)/docs":/home/python/docs sphinx-autobuild

The documentation should served at http://127.0.0.1:8000. It will be rebuild when a file is changed.

Image Variants

The sphinx-doc images come in many flavours, each designed for a specific use case.

All images have the enchant package installed. It is required by sphinxcontrib-spelling to spell check the documentation.

Processes inside the containers run as non-privileged user python to improve security.

Python packages are installed into a virtual environment to isolate them from the operating system.

sphinx-doc:<version>

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of. This tag is based off of python:alpine, which is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general.

sphinx-doc:latex

This image is based off of python and contains all packages needed to build the LaTeX documentation. Because the python image is based on buildpack-deps and includes large number of common Debian packages the resulting image is much larger than the other variant.

Code of Conduct

Everyone interacting in the docker-sphinx-doc project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the PyPA Code of Conduct.

License

Distributed under the BSD 3-Clause license.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Copyright 2017-2019 Markus Zapke-Gründemann