Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/devilbox/docker-python-sphinx
https://github.com/devilbox/docker-python-sphinx
Last synced: 3 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/devilbox/docker-python-sphinx
- Owner: devilbox
- Created: 2019-12-01T09:37:50.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-05-19T11:10:06.000Z (over 3 years ago)
- Last Synced: 2023-08-05T17:12:07.909Z (over 1 year ago)
- Language: Shell
- Size: 19.5 KB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Python Sphinx Docker image
[](https://github.com/devilbox/docker-python-sphinx/releases)
[](https://gitter.im/devilbox/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://devilbox.discourse.group)
[](https://hub.docker.com/r/devilbox/python-sphinx)
[](https://opensource.org/licenses/MIT)
[](https://github.com/devilbox/docker-python-sphinx/actions?query=workflow%3Alint)
[](https://github.com/devilbox/docker-python-sphinx/actions?query=workflow%3Abuild)
[](https://github.com/devilbox/docker-python-sphinx/actions?query=workflow%3Anightly)
This project provides a Python Sphinx Docker image for development purposes.
View **[Dockerfile](https://github.com/devilbox/docker-python-sphinx/blob/master/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-` | 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 |
## Example
For easy usage, there is a Docker Compose example project included.
```bash
cp .env.example .env
docker-compose up
```
```bash
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](#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:
```bash
/
├── index.rst # Sphinx index file
└── conf.py # Sphinx configuration file
```
After you've started the container the structure will look like
```bash
/
├── _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.
```bash
/
├── 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.
```bash
/
├── 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:
```bash
docker run \
--rm \
-v $(pwd)/:/shared/httpd/ \
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.
```bash
docker run \
--rm \
-v $(pwd)/:/shared/httpd/ \
-e NEW_UID=$(id -u) \
-e NEW_GID=$(id -g) \
devilbox/python-sphinx:3.9-dev
```
## Build locally
```bash
# Build default version (Python 3.8)
make build
# Build specific version
make build PYTHON=3.7
```
## Test locally
```bash
# Test default version (Python 3.8)
make test
# Test specific version
make test PYTHON=3.7
```
## License
**[MIT License](LICENSE)**
Copyright (c) 2019 [cytopia](https://github.com/cytopia)