ddidier/sphinx-doc

NDD Docker Sphinx

概述

[NDD Docker Sphinx]是一个基于Sphinx的文档构建工具镜像，支持HTML、实时HTML和PDF等多种格式生成，并集成了大量实用扩展和辅助脚本。镜像版本格式为<SPHINX_VERSION>-<DOCKER_IMAGE_VERSION>，例如3.5.4-9表示使用Sphinx 3.5.4的第9版Docker镜像。

该镜像基于官方https://hub.docker.com/_/python/%E6%9E%84%E5%BB%BA%EF%BC%8C%E9%99%A4Sphinx%E6%A0%B8%E5%BF%83%E5%8A%9F%E8%83%BD%E5%A4%96%EF%BC%8C%E8%BF%98%E9%A2%84%E5%AE%89%E8%A3%85%E5%B9%B6%E9%85%8D%E7%BD%AE%E4%BA%86%E5%A4%9A%E7%A7%8D%E6%89%A9%E5%B1%95%EF%BC%8C%E5%8C%85%E6%8B%AC%E4%B8%BB%E9%A2%98%EF%BC%88%E5%A6%82alabaster%E3%80%81sphinx-rtd-theme%EF%BC%89%E3%80%81%E5%9B%BE%E8%A1%A8%E5%B7%A5%E5%85%B7%EF%BC%88%E5%A6%82sphinxcontrib-mermaid%E3%80%81sphinxcontrib-plantuml%EF%BC%89%E3%80%81%E5%AE%9E%E7%94%A8%E5%B7%A5%E5%85%B7%EF%BC%88%E5%A6%82sphinx-autobuild%E3%80%81sphinx-copybutton%EF%BC%89%E7%AD%89%EF%BC%8C%E5%B9%B6%E6%8F%90%E4%BE%9B%E8%BE%85%E5%8A%A9%E8%84%9A%E6%9C%AC%E7%AE%80%E5%8C%96%E6%97%A5%E5%B8%B8%E6%93%8D%E4%BD%9C%E3%80%82

参考链接：

• Docker Hub镜像：https://hub.docker.com/r/ddidier/sphinx-doc
• 源码仓库：[***]

安装

从源码安装

源码托管于GitLab，可通过以下命令构建：

shell
git clone git@gitlab.com:ddidier/docker-sphinx-doc.git
cd docker-sphinx-doc
make

从Docker Hub安装

Docker镜像可直接从Docker Hub拉取：

shell
export SPHINX_DOC_VERSION="4.1.2-2"
docker pull ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}"

使用

基本要求

• 主机文档目录（下文称${HOST_DATA_DIR}）需挂载到容器内/data目录，使用-v "${HOST_DATA_DIR}":/data参数
• 需通过环境变量USER_ID指定文件所属用户的UID，格式为-e USER_ID="${UID}"

项目初始化

使用sphinx-quickstart-custom命令创建项目骨架，该命令在官方sphinx-quickstart基础上优化了配置文件并添加辅助脚本。注意：${HOST_DATA_DIR}必须已存在，否则会失败。

shell
docker run -it -v "${HOST_DATA_DIR}":/data -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}" sphinx-quickstart-custom

可传递sphinx-quickstart支持的所有参数，例如指定项目名称：

shell
docker run -it -v "${HOST_DATA_DIR}":/data -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}" sphinx-quickstart-custom --project my-documentation

初始化后，建议修改bin/variables.sh配置项目名称和端口等参数。

非交互模式

辅助脚本（推荐）

生成的项目在bin目录下提供辅助脚本，可通过--help查看选项，配置文件为bin/variables.sh。

• 生成HTML文档：

  shell
  ./bin/build-html.sh
  

• 生成HTML并实时预览（支持热重载）：

  shell
  # 默认端口（8000）
  ./bin/serve.sh
  
  # 自定义端口（如12345）
  ./bin/serve.sh --port 12345
  

• 生成PDF文档：

  shell
  ./bin/build-pdf.sh
  

项目根目录还提供Makefile简化操作：

• make html：生成HTML文档
• make pdf：生成HTML和PDF文档
• make serve：生成并预览HTML文档
• make package：打包文档

Docker命令

可直接使用Sphinx命令：

• 查看所有支持的目标：

  shell
  docker run -it --rm -v "${HOST_DATA_DIR}":/data -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}" make help
  

• 生成HTML文档：

  shell
  docker run -it --rm -v "${HOST_DATA_DIR}":/data -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}" make html
  

• 生成HTML并实时预览：

  shell
  # 默认端口（8000）
  docker run -it --rm -v "${HOST_DATA_DIR}":/data -p 8000:8000 -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}" make livehtml
  
  # 自定义端口（如12345）
  docker run -it --rm -v "${HOST_DATA_DIR}":/data -p 12345:12345 -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}" SPHINXPORT=12345 make livehtml
  

• 生成PDF文档：

  shell
  docker run -it --rm -v "${HOST_DATA_DIR}":/data -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}" make latexpdf
  

交互模式

通过以下命令进入容器内部操作：

shell
docker run -it --rm -v "${HOST_DATA_DIR}":/data -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}"

进入容器后，默认位于/data目录（若未在该目录，执行cd /data），可直接使用Sphinx命令：

• make help：查看目标列表
• make html：生成HTML文档
• make latexpdf：生成PDF文档
• make livehtml：生成并预览HTML文档

提示与技巧

若${HOST_DATA_DIR}非文档根目录，可使用-C参数指定目录，例如：

shell
docker run -it --rm -v "${HOST_DATA_DIR}":/data -e USER_ID="${UID}" ddidier/sphinx-doc:"${SPHINX_DOC_VERSION}" make -C /some/directory/ html

配置

内置扩展

镜像预安装以下扩展，可通过修改conf.py启用/禁用：

• 主题：alabaster、guzzle-sphinx-theme、sphinx-bootstrap-theme、sphinx-rtd-theme
• 工具：gitpython、livereload、recommonmark、rinohtype、sphinx-autobuild、sphinx-copybutton、sphinx-prompt、sphinxemoji
• 图表：sphinxcontrib-actdiag、sphinxcontrib-blockdiag、sphinxcontrib-excel-table、sphinxcontrib-fulltoc、sphinxcontrib-git_context、sphinxcontrib-mermaid、sphinxcontrib-nwdiag、sphinxcontrib-plantuml、sphinxcontrib-seqdiag

添加新扩展

如需使用未内置的扩展，需：

1. 创建扩展镜像的Dockerfile：

docker
FROM ddidier/sphinx-doc:latest
RUN pip install '扩展包名 == 版本号'

2. 在source/conf.py中添加扩展：

python
extensions = [
    ...
    '扩展模块名',
]

限制

• PDF生成不支持Excel表格。

开发

编码

Makefile提供开发相关目标：

• make setup：安装开发工具
• make build：构建Docker镜像
• make quality：运行质量检查（ShellCheck）
• make test：运行测试
• make：默认目标，等价于make build quality test

本地使用gitlab-runner测试

1. 启动GitLab Runner服务：

shell
export GITLAB_RUNNER_VERSION=v12.9.0
docker run -d \
    --name gitlab-runner \
    --privileged \
    -v /srv/gitlab-runner/config:/etc/gitlab-runner \
    -v /var/run/docker.sock:/var/run/docker.sock \
    gitlab/gitlab-runner:"${GITLAB_RUNNER_VERSION}"

2. 修改.gitlab-ci.yml，注释镜像拉取步骤

3. 提交修改并构建镜像：

shell
git add --all
git commit -m "测试修改"
make build

4. 运行测试：

shell
docker run --rm -t -i \
    -v /opt/gitlab-runner/config:/etc/gitlab-runner \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v "${PWD}":"${PWD}" \
    --workdir "${PWD}" \
    gitlab/gitlab-runner:"alpine-${GITLAB_RUNNER_VERSION}" \
        exec docker \
            --docker-privileged \
            --docker-pull-policy="if-not-present" \
            --docker-volumes /var/run/docker.sock:/var/run/docker.sock \
            --docker-volumes /builds:/builds \
            Test

发布

Docker Hub不再提供API更新README，发布新版本后需手动更新Docker Hub上的文档。