Skip to content

devilbox/docker-python-sphinx

Repository files navigation

Python Sphinx Docker image

Tag Gitter Discourse type License

lint build nightly

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.

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

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