使用Sphinx生成文档
简介
Sphinx
是由Pocoo Team
这个团队所做的一个文档工具。
Sphinx
的用户群很多, 如Python、OpenCV、Tornado
的文档就是使用它生成的.
如果要看更多的话可以看下http://sphinx-doc.org/examples.html这里, 很多项目都是它作为文档支持的.
Sphinx
的文档是用reStructedText
所写的,主要是由docutils
这个作为底层驱动渲染的, 对比markdown, reStructedText
好像是复杂些.
当然了, 如果直接看github
中的文档, 它这两个都支持在线渲染.
安装
基本Python
安装方法, 下载地址:
https://pypi.python.org/pypi/Sphinx
python setup.py install
即可, 如果遇到依赖包, 一并下载下来再安装.
如果已经安装了pip, easy_install
,可直接使用以下命令安装则可:
pip install -U Sphinx
使用
在项目文件夹中,执行以下命令:
sphinx-quickstart
接下来,按提示完成就会生成一系列初始文件.
sphinx
的文档以rst
结尾,在编写完文档后,使用以下命令则可以生成最终的文档.
make html
在_build/html/index.html
中就可以查看效果了