A Docker image for the Sphinx documentation builder.
The image is based upon the official python:3.6.
Besides the Sphinx documentation builder (sphinx-doc), this image contains:
- alabaster
- gitpython
- guzzle-sphinx-theme
- livereload
- sphinx-autobuild
- sphinx-bootstrap-theme
- sphinx-prompt
- sphinx-rtd-theme
- sphinxcontrib-actdiag
- sphinxcontrib-blockdiag
- sphinxcontrib-excel-table
- sphinxcontrib-fulltoc
- sphinxcontrib-googleanalytics
- sphinxcontrib-googlechart
- sphinxcontrib-googlemaps
- sphinxcontrib-nwdiag
- sphinxcontrib-plantuml
- sphinxcontrib-seqdiag
The versioning scheme of this Docker image is <SPHINX_VERSION>-<DOCKER_IMAGE_VERSION>.
For example, 1.8.1-9 stands for the 9th version of the Docker image using Sphinx 1.8.1.
git clone [email protected]:ndd-docker/ndd-docker-sphinx.git
cd ndd-docker-sphinx
docker build -t ddidier/sphinx-doc .docker pull ddidier/sphinx-docThe 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 inside the container 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.
This is the -e USER_ID=$UID part in the examples of this documentation.
### Initialisation
Sphinx provides the sphinx-quickstart script to create a skeleton of the documentation directory.
You should however use the custom tailored sphinx-init script which:
- calls
sphinx-quickstart - customizes the
Makefile(livehtmltarget) - customizes the configuration file
conf.py(offcial and custom extensions, markdown support, theme)
The directory <HOST_DATA_DIR> must already exist, otherwise the script will fail!
docker run -it -v <HOST_DATA_DIR>:/doc -e USER_ID=$UID ddidier/sphinx-doc sphinx-initAll arguments accepted by sphinx-quickstart are passed to sphinx-init.
For example, you may want to pass the project name on the command line:
docker run -it -v <HOST_DATA_DIR>:/doc -e USER_ID=$UID ddidier/sphinx-doc sphinx-init --project my-documentation### Interactive
The so-called interactive mode is when you issue commands from inside the container.
docker run -it -v <HOST_DATA_DIR>:/doc -e USER_ID=$UID ddidier/sphinx-docYou should now be in the /doc directory, otherwise just cd to /doc.
To see all the official targets, call make help.
To create a PDF document, call make latexpdf.
To create HTML documents, call make html.
The so-called non-interactive mode is when you issue commands from the host directly.
To see all the official targets, call:
docker run -i -v <HOST_DATA_DIR>:/doc -e USER_ID=$UID ddidier/sphinx-doc make helpTo create a PDF document, call make latexpdf.
docker run -i -v <HOST_DATA_DIR>:/doc -e USER_ID=$UID ddidier/sphinx-doc make latexpdfTo create HTML documents, call make html.
docker run -i -v <HOST_DATA_DIR>:/doc -e USER_ID=$UID ddidier/sphinx-doc make htmlTo create HTML documents and watch for changes, call make livehtml:
docker run -it -v <HOST_DATA_DIR>:/doc -p 8000:8000 -e USER_ID=$UID ddidier/sphinx-doc make livehtml
# ^^^^
# open your browser at http://localhost:8000/To trigger a full build while in watch mode, issue from the <HOST_DATA_DIR> folder on the host:
rm -rf build && touch source/conf.pyIf you need the directory <HOST_DATA_DIR> to NOT be the root of the documentation, change the make directory with -C.
Previous commands such as make target become make -C /some/directory/ target.
Please see the pseudo Git extension below for an example.
## Configuration
Warning: to simplify the sphinx-init script, some variables are overriden at the end of the conf.py file.
This is most notably the case of the extensions and html_theme variables.
This image comes with a number of already bundled extensions.
To enable a bundled extension, simply uncomment the associated line in your conf.py.
To disable a bundled extension, simply comment the associated line in your conf.py.
IF you want to use an extension which is not already bundled with this image, you need to:
First extend the image by creating a new 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 conf.py referencing the extension:
extensions = [
...
'a.sphinx.extension',
'another.sphinx.extension',
]This should be extracted in actual Sphinx extensions...
At the time being, the Python code is stored in the subdirectory /_python and is copied when calling sphinx-init.
This pseudo extension reads the properties of a Git repository to display in the left navigation panel and in the footer:
- the current time of the build if any file is not committed or untracked, or
- the name of the tag associated with the last commit if it exists, or
- the hash of the last commit
Enable it by uncommenting the following lines in your conf.py:
# Must be defined somewhere
html_context = {}
import os.path
source_directory = os.path.dirname(os.path.realpath(__file__))
python_directory = os.path.join(source_directory, '_python')
exec(open(os.path.join(python_directory, 'sphinx-git.py'), 'rb').read())This extension requires access to the .git directory:
-
if the documentation is at the same level than the
.gitdirectory:# /my-project # ├── .git # ├── Makefile # ├── build # └── source # └── conf.py docker run -i -v /my-project:/doc -e USER_ID=$UID ddidier/sphinx-doc make html
-
if the documentation is not at the same level than the
.gitdirectory:# /my-project # ├── .git # ├── sources # └── documentation # ├── Makefile # ├── build # └── source # └── conf.py docker run -i -v /my-project:/doc -e USER_ID=$UID ddidier/sphinx-doc make -C /doc/documentation html
- PDF generation does not work when including Markdown file using
recommonmark. - PDF generation does not take into account Excel tables.