sphinx doc 文档生成脚手架工具

sphinx 在python 语言开发中，是一个使用的比较多文档生成脚手架工具，我们帮助我们生成
专业的帮助文档，同时也有远端的免费saas 托管服务，方便分发

安装

sphinx 的安装好多方便，mac 的可以使用brew，或者我们可以使用pip 安装,详细的可以参考官方文档

• mac brew 安装方法

 

brew install sphinx-doc

• pip 安装

pip install -U sphinx

简单demo

sphinx 提供了一个快速生成文档的命令，使用sphinx-quickstart 我们可以快速生成一个可用的文档项目

• sphinx-quickstart

sphinx-quickstart

 

效果

欢迎使用 Sphinx 2.1.0 快速配置工具。

​

请输入接下来各项设置的值（如果方括号中指定了默认值，直接

按回车即可使用默认值）。

​

已选择根路径：.

​

布置用于保存 Sphinx 输出的构建目录，有两种选择。

一是在根路径下创建“_build”目录，二是在根路径下创建“source”

和“build”两个独立的目录。

> 独立的源文件和构建目录（y/n） [n]: y

​

项目名称会出现在文档的许多地方。

> 项目名称: dalongrongdemo

> 作者名称: dalong

> 项目发行版本 []: v1.0

​

如果用英语以外的语言编写文档，你可以在此按语言代码选择语种。

Sphinx 会把内置文本翻译成相应语言的版本。

​

支持的语言代码列表见：

http://sphinx-doc.org/config.html#confval-language。

> 项目语种 [en]: 

​

创建文件 ./source/conf.py。

创建文件 ./source/index.rst。

创建文件 ./Makefile。

创建文件 ./make.bat。

​

完成：已创建初始目录结构。

​

你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。用 Makefile 构建文档，像这样：

 make builder

此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。

 

• 生成html 页面

  sphinx 使用make 进行项目管理，make 可以列出完整的命令

make html

正在运行 Sphinx v2.1.0

making output directory... 完成

构建 [mo]：0 个 po 文件的目标文件已过期

构建 [html]中: 1 个源文件的目标文件已过期

updating environment: 1 added, 0 changed, 0 removed

reading sources... [100%] index                                                                                                                        

查找当前已过期的文件……没有找到

pickling environment... 完成

checking consistency... 完成

preparing documents... 完成

写入输出……[100%] index                                                                                                                                     

生成索引…… genindex

写入附加页面…… search

复制静态文件……完成

复制额外文件……完成

导出 English (code: en) 的搜索索引……完成

导出对象清单……完成

构建 成功.

HTML 页面保存在 build/html 目录。

 

生成的内容

tree build 

build

├── doctrees

│ ├── environment.pickle

│ └── index.doctree

└── html

    ├── _sources

    │ └── index.rst.txt

    ├── _static

    │ ├── alabaster.css

    │ ├── basic.css

    │ ├── custom.css

    │ ├── doctools.js

    │ ├── documentation_options.js

    │ ├── file.png

    │ ├── jquery-3.2.1.js

    │ ├── jquery.js

    │ ├── language_data.js

    │ ├── minus.png

    │ ├── plus.png

    │ ├── pygments.css

    │ ├── searchtools.js

    │ ├── underscore-1.3.1.js

    │ └── underscore.js

    ├── genindex.html

    ├── index.html

    ├── objects.inv

    ├── search.html

    └── searchindex.js

页面效果

• 修改皮肤
  sphinx 默认提供了好多可选的皮肤，我们可以通过修改conf.py 调整，比如：

html_theme = "classic"

重新构建之后的效果

https://sphinx-themes.org/ 网站提供了好多可选的皮肤，提供sphinx_rtd_theme 是用的比较多的一个皮肤

sphinx_rtd_theme 皮肤的安装使用

一般来说我们直接通过pip install sphinx_rtd_theme 然后在执行make html 就可以了，但是可能会有问题，以下会比较保险的安装方法

• 配置venv

 

python3 -m venv venv

• 激活虚拟环境

source venv/bin/activate

• 安装皮肤

pip install sphinx_rtd_theme

• 修改conf.py

html_theme = 'sphinx_rtd_theme'

• 重新构建

make html

• 效果

说明

对于生成的html 文件，我们可以通过minio s3 或者nexus 的raw repo，提供方便的资源访问，同时也可以直接使用github，或者readthedocs
进行托管

参考资料

http://www.sphinx-doc.org
https://sphinx-themes.org/
https://sphinx-rtd-theme.readthedocs.io/en/latest/installing.html