├── .github ├── dependabot.yml └── workflows │ ├── build-ci.yml │ └── build.yml ├── README.rst ├── base └── Dockerfile ├── ci └── Dockerfile └── latexpdf └── Dockerfile /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | # https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates 2 | 3 | version: 2 4 | updates: 5 | - package-ecosystem: "github-actions" 6 | directory: "/" 7 | schedule: 8 | interval: "monthly" 9 | groups: 10 | # Name for the group, which will be used in PR titles and branch names 11 | all-github-actions: 12 | # Group all updates together 13 | patterns: 14 | - "*" 15 | -------------------------------------------------------------------------------- /.github/workflows/build-ci.yml: -------------------------------------------------------------------------------- 1 | name: Create Docker image for CI 2 | 3 | on: 4 | push: 5 | branches: ['master'] 6 | 7 | jobs: 8 | build: 9 | if: github.repository_owner == 'sphinx-doc' 10 | runs-on: ubuntu-latest 11 | steps: 12 | - uses: actions/checkout@v4 13 | - uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3.6.0 14 | - uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3.10.0 15 | - name: Log in to Docker Hub 16 | uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0 17 | with: 18 | username: ${{ secrets.DOCKERHUB_USERNAME }} 19 | password: ${{ secrets.DOCKERHUB_TOKEN }} 20 | - name: Log in to GitHub Container Registry 21 | uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0 22 | with: 23 | registry: ghcr.io 24 | username: ${{ github.actor }} 25 | password: ${{ secrets.GITHUB_TOKEN }} 26 | - name: Extract metadata (tags, labels) for Docker 27 | id: meta 28 | uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 # v5.7.0 29 | with: 30 | images: | 31 | sphinxdoc/docker-ci 32 | ghcr.io/sphinx-doc/sphinx-ci 33 | tags: | 34 | type=schedule,pattern={{date 'YYYY-MM-DD'}} 35 | type=raw,value=latest,enable={{is_default_branch}} 36 | - name: Build and push Docker image 37 | uses: docker/build-push-action@14487ce63c7a62a4a324b0bfb37086795e31c6c1 # v6.16.0 38 | with: 39 | context: ci 40 | platforms: linux/amd64,linux/arm64 41 | push: true 42 | tags: ${{ steps.meta.outputs.tags }} 43 | labels: ${{ steps.meta.outputs.labels }} 44 | -------------------------------------------------------------------------------- /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: Create Docker images 2 | 3 | on: 4 | push: 5 | tags: 6 | - '*.*.*' 7 | 8 | jobs: 9 | build: 10 | if: github.repository_owner == 'sphinx-doc' && startsWith(github.ref, 'refs/tags/') 11 | runs-on: ubuntu-latest 12 | strategy: 13 | matrix: 14 | include: 15 | - name: sphinx 16 | context: base 17 | - name: sphinx-latexpdf 18 | context: latexpdf 19 | steps: 20 | - uses: actions/checkout@v4 21 | - uses: docker/setup-qemu-action@29109295f81e9208d7d86ff1c6c12d2833863392 # v3.6.0 22 | - uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3.10.0 23 | - name: Log in to Docker Hub 24 | uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0 25 | with: 26 | username: ${{ secrets.DOCKERHUB_USERNAME }} 27 | password: ${{ secrets.DOCKERHUB_TOKEN }} 28 | - name: Log in to GitHub Container Registry 29 | uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3.4.0 30 | with: 31 | registry: ghcr.io 32 | username: ${{ github.actor }} 33 | password: ${{ secrets.GITHUB_TOKEN }} 34 | - name: Extract metadata (tags, labels) for Docker 35 | id: meta 36 | uses: docker/metadata-action@902fa8ec7d6ecbf8d84d538b9b233a880e428804 # v5.7.0 37 | with: 38 | images: | 39 | sphinxdoc/${{ matrix.name }} 40 | ghcr.io/sphinx-doc/${{ matrix.name }} 41 | tags: type=pep440,pattern={{version}} 42 | - name: Build and push Docker image 43 | uses: docker/build-push-action@14487ce63c7a62a4a324b0bfb37086795e31c6c1 # v6.16.0 44 | with: 45 | context: ${{ matrix.context }} 46 | platforms: linux/amd64,linux/arm64 47 | push: true 48 | tags: ${{ steps.meta.outputs.tags }} 49 | labels: ${{ steps.meta.outputs.labels }} 50 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | Docker Images for Sphinx_ 3 | ========================= 4 | 5 | Images 6 | ====== 7 | 8 | - ``sphinx`` -- 9 | Main Sphinx image -- 10 | `Docker Hub `__, 11 | `GitHub Container Registry `__ 12 | - ``sphinx-latexpdf`` -- 13 | Image for LaTeX -- 14 | `Docker Hub `__, 15 | `GitHub Container Registry `__ 16 | 17 | .. note:: The ``sphinx-latexpdf`` container contains TeXLive images, 18 | meaning it is very large (over 2GiB). 19 | 20 | Usage 21 | ===== 22 | 23 | Create a Sphinx project: 24 | 25 | .. code:: bash 26 | 27 | $ docker run -it --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-quickstart 28 | 29 | Build HTML document: 30 | 31 | .. code:: bash 32 | 33 | $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-build -M html . _build 34 | 35 | Build EPUB document: 36 | 37 | .. code:: bash 38 | 39 | $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx sphinx-build -M epub . _build 40 | 41 | Build PDF document: 42 | 43 | .. code:: bash 44 | 45 | $ docker run --rm -v /path/to/document:/docs sphinxdoc/sphinx-latexpdf sphinx-build -M latexpdf . _build 46 | 47 | Tips 48 | ==== 49 | 50 | To install additional dependencies, use ``sphinxdoc/sphinx`` as a base image: 51 | 52 | .. code:: dockerfile 53 | 54 | # in your Dockerfile 55 | FROM sphinxdoc/sphinx 56 | 57 | WORKDIR /docs 58 | ADD requirements.txt /docs 59 | RUN python3 -m pip install -r requirements.txt 60 | 61 | Sphinx CI Docker Image 62 | ====================== 63 | 64 | The Docker image used for testing Sphinx_ in continuous integration is defined 65 | in the ``ci`` directory. 66 | 67 | .. _Sphinx: http://www.sphinx-doc.org/ 68 | -------------------------------------------------------------------------------- /base/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM python:slim 2 | 3 | LABEL org.opencontainers.image.authors="Sphinx Team " 4 | LABEL org.opencontainers.image.documentation="https://sphinx-doc.org/" 5 | LABEL org.opencontainers.image.source="https://github.com/sphinx-doc/sphinx-docker-images" 6 | LABEL org.opencontainers.image.version="8.2.3" 7 | LABEL org.opencontainers.image.licenses="BSD-2-Clause" 8 | LABEL org.opencontainers.image.description="Base container image for Sphinx" 9 | 10 | WORKDIR /docs 11 | RUN apt-get update \ 12 | && apt-get install --no-install-recommends --yes \ 13 | graphviz \ 14 | imagemagick \ 15 | make \ 16 | && apt-get autoremove \ 17 | && apt-get clean \ 18 | && rm -rf /var/lib/apt/lists/* 19 | 20 | RUN python3 -m pip install --no-cache-dir --upgrade pip \ 21 | && python3 -m pip install --no-cache-dir Sphinx==8.2.3 Pillow 22 | 23 | CMD ["sphinx-build", "-M", "html", ".", "_build"] 24 | -------------------------------------------------------------------------------- /ci/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM ubuntu:24.04 2 | 3 | ENV DEBIAN_FRONTEND=noninteractive 4 | ENV LANG C.UTF-8 5 | ENV TERM xterm 6 | RUN apt-get update \ 7 | && apt-get upgrade -y \ 8 | && apt-get install -y \ 9 | build-essential \ 10 | dvipng \ 11 | epubcheck \ 12 | git \ 13 | gettext \ 14 | graphviz \ 15 | imagemagick \ 16 | make \ 17 | lmodern \ 18 | openjdk-11-jre-headless \ 19 | python3-venv \ 20 | python3-pip \ 21 | python3-dev \ 22 | texlive-latex-recommended \ 23 | texlive-latex-extra \ 24 | texlive-fonts-recommended \ 25 | tex-gyre \ 26 | texlive-fonts-extra \ 27 | texlive-luatex \ 28 | texlive-xetex \ 29 | && apt-get autoremove \ 30 | && apt-get clean 31 | 32 | RUN mkdir /sphinx 33 | WORKDIR /sphinx 34 | -------------------------------------------------------------------------------- /latexpdf/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM python:slim 2 | 3 | LABEL org.opencontainers.image.authors="Sphinx Team " 4 | LABEL org.opencontainers.image.documentation="https://sphinx-doc.org/" 5 | LABEL org.opencontainers.image.source="https://github.com/sphinx-doc/sphinx-docker-images" 6 | LABEL org.opencontainers.image.version="8.2.3" 7 | LABEL org.opencontainers.image.licenses="BSD-2-Clause" 8 | LABEL org.opencontainers.image.description="LaTeX container image for Sphinx" 9 | 10 | WORKDIR /docs 11 | RUN apt-get update \ 12 | && apt-get install --no-install-recommends --yes \ 13 | graphviz \ 14 | imagemagick \ 15 | make \ 16 | \ 17 | latexmk \ 18 | lmodern \ 19 | fonts-freefont-otf \ 20 | texlive-latex-recommended \ 21 | texlive-latex-extra \ 22 | texlive-fonts-recommended \ 23 | texlive-fonts-extra \ 24 | texlive-lang-cjk \ 25 | texlive-lang-chinese \ 26 | texlive-lang-japanese \ 27 | texlive-luatex \ 28 | texlive-xetex \ 29 | xindy \ 30 | tex-gyre \ 31 | && apt-get autoremove \ 32 | && apt-get clean \ 33 | && rm -rf /var/lib/apt/lists/* 34 | 35 | RUN python3 -m pip install --no-cache-dir --upgrade pip \ 36 | && python3 -m pip install --no-cache-dir Sphinx==8.2.3 Pillow 37 | 38 | CMD ["sphinx-build", "-M", "latexpdf", ".", "_build"] 39 | --------------------------------------------------------------------------------