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
查找当前已过期的文件……没有找到
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
