Python Sphinx Docker image

This project provides a Python Sphinx Docker image for development purposes.

View Dockerfile on GitHub.

Docker Hub	Upstream Project

Documentation

In case you seek help, go and visit the community pages.

Documentation	Chat	Forum
devilbox.readthedocs.io	gitter.im/devilbox	devilbox.discourse.group

Docker image tags

• Image name: devilbox/python-sphinx

Rolling tags

Rolling tags are updated and pushed nightly to ensure latest patch-level Python version.

Image tag	Python version
3.9-dev	Latest 3.9.x
3.8-dev	Latest 3.8.x
3.7-dev	Latest 3.7.x
3.6-dev	Latest 3.6.x
3.5-dev	Latest 3.5.x
2.7-dev	Latest 2.7.x

Release tags

Release tags are fixed and bound to git tags.

Image Tag	Python version
3.9-dev-<git-tag>	Latest 3.9.x
3.8-dev-<git-tag>	Latest 3.8.x
3.7-dev-<git-tag>	Latest 3.7.x
3.6-dev-<git-tag>	Latest 3.6.x
3.5-dev-<git-tag>	Latest 3.5.x
2.7-dev-<git-tag>	Latest 2.7.x

Example

For easy usage, there is a Docker Compose example project included.

cp .env.example .env
docker-compose up

curl localhost:8000

Environment Variables

Variable	Required	Default	Description
SPHINX_PROJECT		.	The sub-directory name under /shared/httpd/ to serve [1]
SPHINX_BUILD_DIR		_build/html	The relative build sub-directory path under SPHINX_PROJECT_DIR
SPHINX_PORT		8000	Docker container internal http port to serve the application
NEW_UID		1000	User id of the host system to ensure syncronized permissions between host and container
NEW_GID		1000	Group id of the host system to ensure syncronized permissions between host and container

• [1] See Project directory structure for usage

Project directory structure

The following shows how to organize your project on the host operating system.

Basic structure

The following is the least required directory structure:

<project-dir>/
├── index.rst                # Sphinx index file
└── conf.py                  # Sphinx configuration file

After you've started the container the structure will look like

<project-dir>/
├── _build
│   └── html
├── index.rst
└── conf.py

Structure with dependencies

The following directory structure allows for auto-installing Python dependencies during startup into a virtual env.

<project-dir>/
├── index.rst                # Sphinx index file
├── conf.py                  # Sphinx configuration file
└── requirements.txt         # Optional: will pip install in virtual env

After you've started the container with a requirements.txt in place, a new venv/ directory will be added with you Python virtual env.

<project-dir>/
├── index.rst                # Sphinx index file
├── conf.py                  # Sphinx configuration file
├── requirements.txt
└── venv
    ├── bin
    ├── include
    └── lib

Mounting your project

When using this image, you need to mount your project directory into /shared/httpd/ into the container:

docker run \
  --rm \
  -v $(pwd)/<project-dir>:/shared/httpd/<project-dir> \
  devilbox/python-sphinx:3.9-dev

If your local uid or gid are not 1000, you should set them accordingly via env vars to ensure to syncronize file system permissions across the container and your host system.

docker run \
  --rm \
  -v $(pwd)/<project-dir>:/shared/httpd/<project-dir> \
  -e NEW_UID=$(id -u) \
  -e NEW_GID=$(id -g) \
  devilbox/python-sphinx:3.9-dev

Build locally

# Build default version (Python 3.8)
make build

# Build specific version
make build PYTHON=3.7

Test locally

# Test default version (Python 3.8)
make test

# Test specific version
make test PYTHON=3.7

License

MIT License

Copyright (c) 2019 cytopia