Sphinx 是一种工具,它允许开发人员以纯文本格式编写文档,以便采用满足不同需求的格式轻松生成输出。这在使用 Version Control System 追踪变更时非常有用。纯文本文档对不同系统之间的协作者也非常有用。纯文本是当前可以采用的最便捷的格式之一。
虽然 Sphinx 是用 Python 编写的,并且最初是为 Python 语言文档而创建,但它并不一定是以语言为中心,在某些情况下,甚至不是以程序员为中心。Sphinx 有许多用处,比如可以用它来编写整本书!
可以将 Sphinx 想像成为一种文档框架:它会抽象化比较单调的部分,并提供自动函数来解决一些常见问题,比如突出显示标题索引和特殊代码(在显示代码示例时),以及突出显示适当的语法。
-----引自 使用 sphinx 制作简洁而又美观的文档
详细的安装和环境配置过程网上已经有很详细的介绍,自行搜索安装即可。
-
安装所有软件后,运行以下命令:
cd: sphinx-quickstart
-
打开index.rst文件,并中添加:
.. automodule:: run :members:
这个是用于自动从模块读取docstring的语句,可以自动从run模块读取文档。
如下图所示:
-
修改conf.py文件
如果现在直接生成,会告诉你找不到run模块,因为Sphinx默认只会从sys.path里加载模块,所以需要将demo目录加入sys.path,所以现在打开conf.py,添加如下内容:import os import sys sys.path.insert(0, os.path.abspath('../..'))
-
运行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
参考文档:
网友评论