zapier/sphinx

Docker: Sphinx镜像

镜像概述

zapier/sphinx是预配置的Sphinx文档生成工具Docker镜像，旨在简化项目文档的构建、预览与部署流程。该镜像无需本地安装依赖，支持Markdown格式（需配置扩展），适用于各类项目的文档管理需求。

核心功能

• 提供本地开发服务器，实时预览文档内容
• 生成静态HTML文档，可部署至S3等平台
• 兼容Markdown格式（通过扩展配置）
• 统一团队文档构建环境，避免依赖冲突

使用场景

• 项目文档日常编写与实时预览
• 生成静态HTML文档用于线上部署
• 团队协作中标准化文档构建流程

配置说明

基础配置

项目需包含以下文件：

• ./docs/conf.py：Sphinx配置文件
• ./docs/index.rst：根reStructuredText文件

Markdown支持配置

若需使用Markdown格式：

1. 链接README.md为文档入口：ln -s README.md docs/index.md
2. 在docs/conf.py添加扩展：

python
extensions = ['recommonmark', 'sphinx_markdown_tables']

使用示例

运行本地开发服务器

bash
docker run -itv $(PWD):/host -p 8000:8000 zapier/sphinx

访问http://localhost:8000即可预览文档。

构建HTML文档

bash
docker run -itv $(PWD):/host zapier/sphinx sphinx-build docs docs/_build/html

生成的HTML文件位于docs/_build/html目录，可上传至S3等平台。

贡献指南

本地测试

1. 构建镜像：make build
2. 运行测试：make test
3. 启动容器：make run

自动构建与标签

• 推送的更改会在Docker Hub自动构建
• 镜像标签从GitHub Releases自动生成