使用Sphinx生成文档

  1. 简介
  2. 安装
  3. 使用

简介

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中就可以查看效果了