sphinx快速入门

简介

sphinx是一个用于快速生成文档的工具，很是适合生成Python文档。

它具备如下优势：

• 支持多种输出格式， 如html，Latex，ePub等。

• 丰富的扩展

• 结构化文档

• 自动索引

• 支持语法高亮

sphinx使用reStructuredtext做为它的标记语言。

安装

使用pip进行安装：

pip install sphinx

设置源文件目录

包含.rst文件的根目录称之为源文件目录，目录中还包含sphinx的配置文件conf.py。

进入源文件目录，执行如下命令，会指引用户配置整个项目：

sphinx-quickstart

定义文件结构

执行上述命令以后，sphinx会在源文件目录中自动生成conf.py文件以及index.rst。index.rst称之为主文档，它被sphinx做为欢迎页面。

index.rst中包含了目录树指令toctree，sphinx使用它连接其余子文档。

toctree指令的初始值为空：

.. toctree::
   :maxdepth: 2

接下来就能够给它添加子文档的连接了，直接使用文档的名称便可，省略掉文件后缀，若是是多级目录，则使用/分隔开。

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   chapter/doc1
   ...

接着咱们就能够建立上面列出的文件并添加相应内容了，sphnix会自动将这些文档的章节标题插入到doctree指令的位置。

添加内容

在sphinx源文件中，使用reStructuredText标记语言进行文档编写，除此以外，sphinx还格外提供了一些指令。

具体能够参考

reStructuredText Primer 以及
Sphinx Markup Constructs

生成文档

使用下面的命令生成文档：

$ sphinx-build -b html sourcedir builddir

sourcedir指源文件目录，生成的文档放置在builddir指定的目录中。

实际上还有一个更简便的方法，sphinx-quickstart生成了一个make.bat文件，能够直接运行这个脚本：

make html

上述命令会直接在源文件目录中生成文档。

对象文档

sphinx的设计初衷之一就是更容易生成任何域中对象的文档，域指不少对象的集合，这些对象中还包含了相应的文档注释。

最主要的域是Python域， 例如python内置函数enumerate()的注释文档以下所示：

.. py:function:: enumerate(sequence[, start=0])

   Return an iterator that yields tuples of an index and an item of the
   *sequence*. (And so on.)

它将被渲染成以下格式：

enumerate(sequence[, start=0])

　　Return an iterator that yields tuples of an index and an item of the sequence. (And so on.)
　　
指令参数是咱们须要描述的对象，内容是咱们编写的文档注释。因为Python是默认的域，因此并不须要特别指出所属的域来。

.. function:: enumerate(sequence[, start=0])

   ...

sphinx还提供了一些指令用于生成其余对象类型的文档。例如py:class以及py:method

基本配置

sphinx经过conf.py进行配置，conf.py使用python语法，默认以utf-8编码保存。具体配置请查看 The build configuration file。

自动生成文档注释

sphinx支持从python源代码中提取文档注释信息，而后生成文档，咱们将这称之为autodoc。

为了使用autodoc，首先须要在配置文件的extensions选项中添加'sphinx.ext.autodoc'。而后咱们就可使用autodoc的指令了。

例如，生成函数io.open()的文档，只须要在rst文件中添加以下语句：

.. autofunction:: io.open

也能够直接生成整个类的文档：

.. automodule:: io
   :members:

为了提取文档注释，autodoc须要导入注释所在的模块。所以须要在sys.path中设置好模块的路径。

设置主题

推荐使用readthedoc使用的主题，美观又简洁大方。
首先安装主题库：

pip install sphinx_rtd_theme

而后配置conf.py:

import sphinx_rtd_theme

html_theme = "sphinx_rtd_theme"

html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

简书地址