Python sphinx-build在Windows系统中生成Html文档

Posted 2020-09-08

看到前同事发布的“Markdown/reST 文档发布流水线”基于TFS、Docker、Azure等工具和平台进行文档发布的介绍说明，不得不在心中暗暗竖起大拇指。这套模式，实现了文档编写后版本管理、发布、存档、分享的高度自动化，它不仅仅可以应用在文章中介绍的技术文档发布模式，同样也适用于我们大多数web、app等软件生命周期过程模式。DevOps一词的盛行，绝对不是软件行业中又一个流行语的鼓吹和炒作，而是软件过程的一种发展和进化。结合自动化平台、Docker、云平台等优秀技术和产品、软件的过程模式将会越来越高效，使得产品的发布周期越来越密集、信息技术将会对我们的生活便利性发挥出更大的推动力。

在仔细阅读和分析分析了文章中的相关内容，因文章中提到TFS、持续集成、Azure等都比较熟悉，但同时也非常有兴趣于文章提到的reST生成过程，于是着手验证和体验了一下如何把一个平面文档生成一个带导航、有组织、体检良好的用户文档。

下面是把rst文档生成为html的工具配置和组织相关文档的过程记录。

1， 下载安装Python

2， 下载Python包SetupTools

检查Python目录下的子目录Scripts是否存在easy_install.exe文件，如果存在请继续第三步，不存在请下载https://pypi.python.org/pypi/setuptools zip包，解压后放到Python安装的根文件夹下面，并该目录加入到环境变量中。

3， 安装Sphinx

启动CMD，并运行命令”easy_install sphinx”，该过程需要一段时间，安装过程中有warning，并长时间等待时，可以按键盘的任意键，继续运行，直到安装完成。

 

 

4， 准备rst文档及相关目录

目录结构包含如下，其中docs文件夹包含rst文件。Conf.py存放sphinx-build命令的相关参数，可以根据模板自己文档内容进行修改。

 

 

该示例,在docs文件中存放了一个文件index.rst，内容如下：

 

 

5， 构建rst文档

在rst文档所在的项目目录下运行cmd，运行“sphinx-build -b html ./docs/ ./build/”

运行结果如下，出现无法导入sphinx_rtd_theme 模块异常信息。

 

 

6， 安装sphinx_rtd_theme

在cmd中运行“pip install sphinx_rtd_theme”，安装相应的模块。

 

 

7， 再次构建rst文档，生成html文档

 

 

8， 构建结果

在rst文档中的build目录中生成了根据rst文档创建的html及相关文档。