Question

首先，需要在项目的顶层目录运行sphinx-quickstart。这会创建Sphinx需要的目录结构，同时会在文件夹doc/source中创建两个文件，一个是conf.py，它包含Sphinx的配置信息（当然也是Sphinx运行所必需的），另一个文件是index.rst，它将作为文档的首页。

然后就可以通过在调用命令sphinx-build时给出源目录和输出目录来生成HTML格式的文档：

$ sphinx-build doc/source doc/build
　import pkg_resources
Running Sphinx v1.2b1
loading pickled environment... done
No builder selected, using default: html
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
looking for now-outdated files... none found
preparing documents... done
writing output... [100%] index
writing additional files... genindex search
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded.

现在就可以在心仪的浏览器中打开doc/build/index.html并开始阅读文档了。

提示

如果使用了setuptools或者pbr（参见4.2节）进行打包，Sphinx会对它们进行扩展以支持命令setup.py build_sphinx，这个命令会自动运行sphinx-build。pbr对Sphinx包含比较完善的默认配置，如输出文档到doc子目录中。

index.rst是文档开始的地方，但并不局限于此。reST支持包含，所以完全可以将文档分成多个文件。刚开始不必太担心语法和语义，尽管reST确实提供了不少格式，但后面有很多时间去了解。reST的完全指南（http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html）介绍了如何创建标题、列表、表格等。