Using sphinx to build Python document

使用sphinx-quickstart命令来初始化创建一些必要的文件（建议先创建一个docs文件夹，然后在其中执行该命令）。

使用sphinx-build命令来生成对应的文档，比如sphinx-build -b html source build会生成html格式的页面。当然，如果你在执行sphinx-quickstart命令时选择了同时生成Makefile的话，则可以通过make html来达到一样的效果。

使用sphinx-build命令来生成文档时，并不需要指定对应的项目路径，原因在于sphinx是直接在python代码中import你在rst文件中填写的模块的。因此，一定要确保在所有依赖包都安装好的virtualenv中来执行sphinx-build命令（sphinx最好也安装在该virtualenv中），并且，确保对应的项目路径可以在python环境中被import（把项目路径添加到PYTHONPATH环境变量中再执行命令或是在项目路径的父级目录执行命令）。 比如下面的rst:

.. autoclass:: my_module.sub_module.ClassA

实际上做的事情类似于：

from my_module.sub_module import ClassA

使用sphinx-apidoc -f -o docs/source projectdir来自动生成对应于项目中每个函数的api的文档。

建议加入sphinx.ext.napoleon扩展，这样在转换代码中的docstring时会支持google和numpy的风格（example）。

sphinx默认会渲染所有的rst格式的文件，如果想要使用mark down来书写文档的话，需要额外安装解析mark down的库，并设置sphinx来渲染它们（参考http://www.sphinx-doc.org/en/master/usage/markdown.html）。

避免重复渲染同一个文件：默认所有文件夹下的rst文件都会被sphinx渲染，所以在rst文件中直接引用该文件名即可，而不需要.. include:来引入。 比如，我有一个api.rst文件，我需要在index.rst文件中引用它作为目录：

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   api

​