Public | Automated Build

Last pushed: 5 months ago
Short Description
The Sphinx documentation builder for HTML and PDF with live reload and commons plugins.
Full Description

NDD Docker Sphinx

A Docker image for the Sphinx documentation builder.

The image is based upon the official python:2.7.

Besides the Sphinx documentation builder (sphinx-doc), this image contains:


From source

git clone
cd ndd-docker-sphinx
docker build -t ddidier/sphinx-doc .

From Docker Hub

docker pull ddidier/sphinx-doc


The documentation directory on the host <HOST_DATA_DIR> must be mounted as a volume under /doc in the container. Use -v <HOST_DATA_DIR>:/doc to use a specific documentation directory or -v $(pwd):/doc to use the current directory as the documentation directory.

Sphinx will be executed by the sphinx-doc user which is created by the Docker entry point. You must pass to the container the environment variable USER_ID set to the UID of the user the files will belong to. For example -e USER_ID=`id -u $USER` .


Sphinx provides the sphinx-quickstart script to create a skeleton of the documentation directory. You should however use the provided sphinx-init script which first calls sphinx-quickstart then configures the provided extensions.

docker run -it -v <HOST_DATA_DIR>:/doc -e USER_ID=`id -u $USER` ddidier/sphinx-doc sphinx-init

All arguments accepted by sphinx-quickstart are passed to sphinx-init. For example:

docker run -it -v <HOST_DATA_DIR>:/doc -e USER_ID=`id -u $USER` ddidier/sphinx-doc sphinx-init --project my-documentation


docker run -it -v <HOST_DATA_DIR>:/doc -e USER_ID=`id -u $USER` ddidier/sphinx-doc

You should now be in the /doc directory, otherwise just cd to /doc.

To create a new Sphinx project, call sphinx-init.

To create HTML documents, call make html.

To create a PDF document, call make pdf.

To watch for changes and create HTML documents dynamically, call make livehtml with a port binding:

docker run -it -v <HOST_DATA_DIR>:/doc -p 8000:8000 -e USER_ID=`id -u $USER` ddidier/sphinx-doc make livehtml

To trigger a full build while in watch mode, issue from the <HOST_DATA_DIR> folder:

rm -rf build && touch source/

Non interactive

docker run -i -v <HOST_DATA_DIR>:/doc -e USER_ID=`id -u $USER` ddidier/sphinx-doc make html
docker run -i -v <HOST_DATA_DIR>:/doc -e USER_ID=`id -u $USER` ddidier/sphinx-doc make pdf


Enable an extension

To enable an already installed extension, uncomment the line in your

extensions = [
  # 'sphinxcontrib.googleanalytics',
  # 'sphinxcontrib.libreoffice',

Install an extension

To install a new extension, first extend the Dockerfile:

FROM ddidier/sphinx-doc:latest

RUN pip install 'a-sphinx-extension       == A.B.C' \
                'another-sphinx-extension == X.Y.Z'

Then add a line in your

extensions = [

Enable Markdown

To use Markdown inside of Sphinx, add this to your

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,

source_suffix = ['.rst', '.md']

This allows you to write both .md and .rst files inside of the same project.

Docker Pull Command
Source Repository

Comments (0)