×

sphinx入门指南【1】快速入门

96
nummy
2016.10.20 20:30* 字数 956

简介

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()]
sphinx
Web note ad 1