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