Sphinx + rseStructuredText 生成 html 格式文档

Sphinx 是一种工具，它允许开发人员以纯文本格式编写文档，以便采用满足不同需求的格式轻松生成输出。这在使用 Version Control System 追踪变更时非常有用。纯文本文档对不同系统之间的协作者也非常有用。纯文本是当前可以采用的最便捷的格式之一。

虽然 Sphinx 是用 Python 编写的，并且最初是为 Python 语言文档而创建，但它并不一定是以语言为中心，在某些情况下，甚至不是以程序员为中心。Sphinx 有许多用处，比如可以用它来编写整本书！

可以将 Sphinx 想像成为一种文档框架：它会抽象化比较单调的部分，并提供自动函数来解决一些常见问题，比如突出显示标题索引和特殊代码（在显示代码示例时），以及突出显示适当的语法。

-----引自 使用 sphinx 制作简洁而又美观的文档

详细的安装和环境配置过程网上已经有很详细的介绍，自行搜索安装即可。

1. 安装所有软件后，运行以下命令：

   cd: sphinx-quickstart
   

2. 打开index.rst文件，并中添加：

   .. automodule:: run
      :members:
   

   这个是用于自动从模块读取docstring的语句，可以自动从run模块读取文档。

   如下图所示：

Image 1.png

3. 修改conf.py文件
   如果现在直接生成，会告诉你找不到run模块，因为Sphinx默认只会从sys.path里加载模块，所以需要将demo目录加入sys.path，所以现在打开conf.py，添加如下内容：

   import os
   import sys
   sys.path.insert(0, os.path.abspath('../..'))
   

4. 运行Sphinx生成html文档

   sphinx-build -b html source build
   make html
   

注意：

• make html命令要切换到source所在文件夹的根目录

  • windows下切换到上一级目录命令：cd..
  • windows下切换到下一级目录命令：cd 文件目录名

• rst格式文件和index.rst文件要放到source目录中

  最终生成的index.html文件，即目录跳转页如下：

  Image 4.png

参考文档：

• 使用 sphinx 制作简洁而又美观的文档
• 使用Sphinx为你的python模块自动生成文档
• rst语法