首先点进来的应该都知道 sphinx， 一个 python 支持的项目文档框架， 使用 reStructuredText(.rst)语法规则进行文档编写 语法入门 点击这里，实验环境 python3.7.2 venv：
Xnip2019-11-19_09-21-57.png
- 安装 sphinx
pip install sphinx sphinx-autobuild sphinx_rtd_theme
- 创建文档项目，配置项目信息
(venv) Qinfeis-MacBook-Pro:docs Qinfei$ sphinx-quickstart
欢迎使用 Sphinx 2.0.1 快速配置工具。
请输入接下来各项设置的值（如果方括号中指定了默认值，直接
按回车即可使用默认值）。
已选择根路径：.
布置用于保存 Sphinx 输出的构建目录，有两种选择。
一是在根路径下创建“_build”目录，二是在根路径下创建“source”
和“build”两个独立的目录。
> 独立的源文件和构建目录（y/n） [n]: y
项目名称会出现在文档的许多地方。
> 项目名称: ccc管理系统
> 作者名称: 蜡笔不小新
> 项目发行版本 []: v0.01
如果用英语以外的语言编写文档，你可以在此按语言代码选择语种。
Sphinx 会把内置文本翻译成相应语言的版本。
支持的语言代码列表见：
http://sphinx-doc.org/config.html#confval-language。
> 项目语种 [en]: zh
创建文件 ./source/conf.py。
创建文件 ./source/index.rst。
创建文件 ./Makefile。
创建文件 ./make.bat。
完成：已创建初始目录结构。
你现在可以填写主文档文件 ./source/index.rst 并创建其他文档源文件了。用 Makefile 构建文档，像这样：
make builder
此处的“builder”是支持的构建器名，比如 html、latex 或 linkcheck。
- 修改 conf.py 文件 （我创建了 src 文件夹，用来放置自己编写的 rst 文档）
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('../src'))
# 换个好看的主题
html_theme = 'sphinx_rtd_theme'
- 编写并链接文档到 index.rst
编辑index.rst,进行引用文件
.. toctree::
:maxdepth: 2
:caption: Contents:
概述 <src/description>
- 生成 html 文件
make html
- 发布文档
找个支持静态网页文件的地方放置即可，可选 自建nginx、 oss、 git 的pages 、readthedocs等 == 主要看个人心情和口袋里的cions
如果本来有 markdown 文档，可以使用 pandoc 进行文档转换，由于文档转换不是本文重点，pandoc 的安装这里就不写了
pandoc -s -t rst --toc markdown.md -o index.rst
参考文档：
https://blog.csdn.net/qq_26848099/article/details/83583612
https://segmentfault.com/a/1190000007233355
https://zh-sphinx-doc.readthedocs.io/en/latest/contents.html
https://docs-python2readthedocs.readthedocs.io/en/master/configure-sphinx.html
https://www.sphinx-doc.org/en/1.8/usage/quickstart.html
