不同文档系统的转换

这一节搜集了一些有用的提示，帮助我们从其他的文档系统迁移到reStructuredText/Sphinx.

• Gerard Flanagan （人名）写了一个脚本把纯净的HTML转换为 reST文本; 你可以到 Python 索引页 查看.
• 原来的Python文档转换为 Sphinx, 代码托管在 the Python SVN repository. 它包含将Python-doc-style LaTeX 标记转换为Sphinx reST 的生成代码.
• Marcin Wojdyr 写了一个脚本，将 Docbook 转换为 reST ; 可查看 Google Code.
• Christophe de Vienne 写了一个将 Open/LibreOffice 文档转换为 Sphinx的工具: odt2sphinx.
• 转换不同的标记语言, Pandoc 也是一个非常有用的工具.

在其他系统中使用

请参考 pertinent section in the FAQ list.

前提

Sphinx 运行前需要安装 Python 2.4 或者 Python 3.1 , 以及 docutils 和 Jinja2 库. Sphinx 必须工作在 0.7 版本及一些 SVN 快照(不能损坏). 如果需要源码支持高亮显示，则必须安装 Pygments 库.

如果使用 Python 2.4 ，还需要 uuid.

用法

更深入的话题,请参考 Sphinx初尝 .

配置文档源

文档集的根目录叫 source directory. 该目录也包含了 Sphinx 的配置文件 conf.py, 在这里你可以配置Sphinx各个方面，使Sphinx按照你的要求读取源文件并创建文档. [1]

Sphinx 有个脚本叫做 sphinx-quickstart ,它可以帮你建立源目录及默认配置文件 conf.py ，它通过几个简单的问题获取一些有用的配置值. 你仅需要运行

$ sphinx-quickstart

然后回答这些问题. (其中”autodoc” 扩展选项请选中.)

它也会自动匹配 “API 文档” 生成器 sphinx-apidoc; 详细信息请参考 调用 sphinx-apidoc.

定义文档结构

假定你已经运行了 sphinx-quickstart . 它创建了源目录，包含 conf.py 及一份主文档 index.rst (如果你接受了默认选项).主文档 master document 的主要功能是被 转换成欢迎页, 它包含一个目录表（ “table of contents tree”或者 toctree ). Sphinx 主要功能是使用 reStructuredText, 把许多文件组织成一份结构合理的文档.

toctree 指令初始为空, 如下:

.. toctree::
   :maxdepth: 2

你可以在 content 的位置添加文档列表:

.. toctree::
   :maxdepth: 2

   intro
   tutorial
   ...

以上精确展示toctree 与文档的转换. 所有的文档以文件名 document names的形式给出, 不需文件后缀名;使用斜线作为目录分隔符.

更多信息请查看 the toctree directive.

现在可以创建toctree指令后的文件及目录了， 它们的章节标题被插入到toctree指令的位置 (与 “maxdepth” 同一缩进) . 现在Sphinx已知道文档的分层结构. (toctree指令后的文件也可以有 toctree 指令, 会生成更深的层次结构.)

添加内容

在Sphinx源文件里, 可以使用reStructuredText的很多特性. 也有些特性被添加到Sphinx中. 例如, 可以引用参考文件链接 (对所有输出类型均有效) ，使用 ref 角色.

又如, 浏览HTML版本时想要查看文档的源文件，只需点击边框栏的”显示源代码”.

reStructuredText 简介 详细介绍了reStructuredText

Sphinx标记的组成 列出了Sphinx添加的全部标记.

运行创建工具

现在已经添加了一些文件,下面可以创建文档了. 创建工具 sphinx-build , 使用方式

$ sphinx-build -b html sourcedir builddir

sourcedir 是源目录 source directory , builddir 则是放置生成的文档的根目录. -b 是创建工具的选项;这个例子创建HTML文件.

调用 sphinx-build 列出工具 sphinx-build 支持的所有选项.

而且, sphinx-quickstart 脚本创建的 Makefile 和

make.bat 使操作更容易，仅需运行

$ make html

创建 HTML 在设定好的目录里. 执行 make 将不需要任何参数.

文档对象

Sphinx的对象 objects (一般含义）在任何 domain （主域）里是指简单的文档. 一个主域包含所有的对象类型, 完整的生成标记或引用对象的描述. 最著名的主域是Python 主域. Python文档建立函数 enumerate() , 在源文件里添加:

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

   返回一个迭代器，输出包含索引及*sequence*里所有条目的元组.

返回形式为:

enumerate(sequence[, start=0])

返回一个迭代器，输出包含索引及*sequence*里所有条目的元组

指令的参数是对象的描述标示 signature , 内容是对它的说明.同一行可以写多个参数.

Python 主域通常是默认的, 因此不需要特别标记出主域的名字:

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

   ...

以上在默认主域配置下效果是等同的.

对不同的Python 对象有不同的指令, 如 py:class 或者 py:method . 不同的对象类型有不同的引用角色 role . 这个标记将创建链接到文档的 enumerate()

这个 :py:func:`enumerate` 函数用于 ...

这是一个实例: 可链接 enumerate() .

同样如果默认为 Python 主域 py: 可以省略. 但这不重要，Sphinx会自动发现包含 enumerate() 的文件并且链接.

不同主域对于不同标示有特定的角色，以使输出格式更美观，在C/C++ 主域里增加了链接到元素类型的角色.

Sphinx Domains 列出所有主域及其指令/角色.

基本配置

前面提到的文件 conf.py ，控制着Sphinx怎样生成文档. 这个文件以Python 源文件的形式执行你的配置信息 . 高级的使用者则通过Sphinx使其执行, 可以配置它实现不平凡的任务, 例如继承 sys.path 或者导入 模块标示文档的版本.

仅需要修改 conf.py ,可以改变默认值, 删除一些符号，修改对应的值. (通过标准的 Python 操作符: # 为注释行).或者通过 sphinx-quickstart 初始化一些值. 自定义的配置一般不会由 sphinx-quickstart 自动产生,需要自己添加标记. 记住此文件使用Python 的操作符及字符串、数字、列表等.这个文件默认保存为UTF-8编码, 首行需要添加编码声明. 插入非ASCII字符, 则需要使用Python Unicode 字符串 (如 project = u'Exposé' ).

详情查看 The build configuration file .

自动文档

Python 源代码的文档字符串一般放置了许多的说明信息. Sphinx 支持自动摄取这些说明信息, 使用 “autodoc”的扩展 extension (标准的Python模块扩展,为Sphinx提供的附加功能).

使用autodoc, 需在配置里激活，在 conf.py 放入字符串 'sphinx.ext.autodoc' 位置在 :confval:`extensions` 配置值列表. 现在已配置了一些附加指令.

如,文档化函数 io.open() ,读取源码的标示及文档字符串,这样写:

.. autofunction:: io.open

也可以读取整个类或模块, 使用选项

.. automodule:: io
   :members:

autodoc 需要导入到你的模块以便索取文档字符串. 因此,在 conf.py 需要为 sys.path 添加合适的路径.

详情请参考 sphinx.ext.autodoc .

其他话题

• 其他扩展 (math, intersphinx, viewcode, doctest)
• 静态文件
• 选择主题
• 模板
• 使用扩展
• 写扩展

尾注

Makefile 选项

文件 Makefile 及 make.bat 由 sphinx-quickstart 创建，脚本 sphinx-build 仅使用选项 -b 和 -d .它们则支持以下自定义行为的变量:

PAPER

:confval:`latex_paper_size` 的值.

SPHINXBUILD

命令 sphinx-build 替代值.

BUILDDIR

替代运行 sphinx-quickstart 选择的目标目录.

SPHINXOPTS

sphinx-build 的额外选项.

段落

段落 (:duref:`ref <paragraphs>`) 是reST 文件的基本模块. 段落是由空行分隔的一段文本. 和Python一样, 对齐也是reST的操作符, 因此同一段落的行都是左对齐的.

内联标记

标准的reST 内联标记相当简单:

• 星号: *text* 是强调 (斜体),
• 双星号: **text** 重点强调 (加粗),
• 反引号: ``text`` 代码样式.

星号及反引号在文本中容易与内联标记符号混淆，可使用反斜杠符号转义.

标记需注意的一些限制:

• 不能相互嵌套,
• 内容前后不能由空白: 这样写``* text*`` 是错误的,
• 如果内容需要特殊字符分隔. 使用反斜杠转义，如: thisis\ *one*\ word.

这些限制在未来版本可能会被改善.

reST 也允许自定义 “文本解释角色”’, 这意味着可以以特定的方式解释文本. Sphinx以此方式提供语义标记及参考索引，操作符为 :rolename:`content`.

标准reST 提供以下规则:

• :durole:`emphasis` – 写成 *emphasis*
• :durole:`strong` – 写成 **strong**
• :durole:`literal` – 写成 ``literal``
• :durole:`subscript` – 下标
• :durole:`superscript` – 上标
• :durole:`title-reference` – 书、期刊等材料的标题

详情请查看 内联标记 .

列表与引用

列表标记 (:duref:`ref <bullet-lists>`) 的使用最自然: 仅在段落的开头放置一个星号和一个缩进. 编号的列表也可以;也可以使用符号 # 自动加序号:

* 这是一个项目符号列表.
* 它有两项，
  第二项使用两行.

1. 这是个有序列表.
2. 也有两项.

#. 是个有序列表.
#. 也有两项.

列表可以嵌套，但是需跟父列表使用空行分隔

* 这是
* 一个列表

  * 嵌套列表
  * 子项

* 父列表继续

定义列表 (:duref:`ref <definition-lists>`)

术语 (term 文本开头行)
   定义术语，必须缩进

   可以有多段组成

下一术语（term）
   描述.

一行仅能写一个术语.

引用段落 (:duref:`ref <block-quotes>`) 仅使用缩进（相对于周围段落）创建.

行模块 (:duref:`ref <line-blocks>`) 可以这样分隔

| 这些行
| 在源文件里
| 被分隔的一模一样.

还有其他有用的模块:

• 字段列表 (:duref:`ref <field-lists>`)
• 选项列表(:duref:`ref <option-lists>`)
• 字面引用模块 (:duref:`ref <quoted-literal-blocks>`)
• 文档测试模块 (:duref:`ref <doctest-blocks>`)

源代码

字面代码块 (:duref:`ref <literal-blocks>`) 在段落的后面使用标记 :: 引出. 代码块必须缩进(同段落，需要与周围文本以空行分隔):

这是一段正常文本. 下一段是代码文字::

   它不需要特别处理，仅是
   缩进就可以了.

   它可以有多行.

再是正常的文本段.

这个 :: 标记很优雅:

• 如果作为独立段落存在,则整段都不会出现在文档里.
• 如果前面有空白，则标记被移除.
• 如果前面是非空白，则标记被一个冒号取代.

因此上面的例子第一段文字将变为”下一段是代码文字:”.

表格

支持两种表格. 一种是 网格表格 (:duref:`ref <grid-tables>`), 可以自定义表格的边框. 如下:

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+

简单表格 (:duref:`ref <simple-tables>`) 书写简单, 但有一些限制: 需要有多行，且第一列元素不能分行显示，如下:

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

超链接

段落里包含 `a link`_.

.. _a link: http://example.com/

章节

章节的标题 (:duref:`ref <sections>`) 在双上划线符号之间（或为下划线）, 并且符号的长度不能小于文本的长度:

=================
This is a heading
=================

通常没有专门的符号表示标题的等级，但是对于Python 文档，可以这样认为:

• # 及上划线表示部分
• * 及上划线表示章节
• =, 小章节
• -, 子章节
• ^, 子章节的子章节
• ", 段落

当然也可以标记（查看 reST 文档), 定义章节的层次，但是需要注意输出格式(HTML, LaTeX)所支持的层次深度 .

显式标记

显式标记”Explicit markup” (:duref:`ref <explicit-markup-blocks>`) 用在那些需做特殊处理的reST结构中, 如尾注，突出段落，评论，通用指令.

显式标记以 .. 开始，后跟空白符，与下面段落的缩进一样. (在显示标记与正常的段落间需有空行，这听起来有些复杂，但是写起来会非常直观.)

指令

指令 (:duref:`ref <directives>`) 是显式标记最常用的模块. 也是reST 的扩展规则, 在 Sphinx 经常被用到.

文档工具支持以下指令:

• 警告: :dudir:`attention`, :dudir:`caution`, :dudir:`danger`, :dudir:`error`, :dudir:`hint`, :dudir:`important`, :dudir:`note`, :dudir:`tip`, :dudir:`warning` 及通用标记 :dudir:`admonition`. (大多数模式仅支持 “note” 及 “warning” )

• 图像:

  • :dudir:`image` (详情可看下面的 图像 )
  • :dudir:`figure` (有标题及可选说明的图像)

• 额外的主体元素:

  • :dudir:`contents <table-of-contents>` (本地，仅是当前文件的内容表格)
  • :dudir:`container` (自定义容器，用来生成HTML的 <div> )
  • :dudir:`rubric` (和文档章节无关的标题)
  • :dudir:`topic`, :dudir:`sidebar` (高亮显示的主体元素)
  • :dudir:`parsed-literal` (支持内联标记的斜体模块)
  • :dudir:`epigraph` (可选属性行的摘要模块)
  • :dudir:`highlights`, :dudir:`pull-quote` (有自己的类属性的摘要模块)
  • :dudir:`compound` ( 复合段落)

• 专用表格:

  • :dudir:`table` (有标题的表格)
  • :dudir:`csv-table` (CSV自动生成表格)
  • :dudir:`list-table` (列表生成的表格)

• 专用指令:

  • :dudir:`raw` (包含原始格式的标记)
  • :dudir:`include` (包含reStructuredText标记的文件) – 在Sphinx中,如果包含绝对文件路径，指令会以源目录地址做为参照
  • :dudir:`class` (将类属性指派给下一个元素) [1]

• HTML 特性:

  • :dudir:`meta` (生成HTML <meta> 标签)
  • :dudir:`title` (覆盖文档标题)

• 影响标记:

  • :dudir:`default-role` (设置新的默认角色)
  • :dudir:`role` (创建新的角色)

  如果仅有一个文件，最好使用 :confval:`default_role`.

设置不使用指令 :dudir:`sectnum`, :dudir:`header` 及 :dudir:`footer`.

Sphinx 新增指令可查阅 Sphinx标记的组成.

指令有名字，参数，选项及内容组成. (记住这些，在下面一小节中自定义指令里会用到).来看一个例子:

.. function:: foo(x)
              foo(y, z)
   :module: some.module.name

   返回用户输入的一行文本.

function 是指令名字. 在第一行和第二行给出了两个参数, 及一个选项 module (如你所见，选项在参数后给出，由冒号引出). 选项必须与指令有一样的缩进.

指令的内容在隔开一个空行后，与指令有一样缩进.

图像

reST 支持图像指令 (:dudir:`ref <image>`), 如下:

.. image:: gnu.png
   (选项)

这里给出的文件名( gnu.png) 必须是源文件的相对路径，如果是绝对路径则以源目录为根目录. 例如，在文件 sketch/spam.rst 引用图像 images/spam.png ，则使用 ../images/spam.png 或者 /images/spam.png.

Sphinx 会自动将图像文件拷贝到输出目录的子目录里，( 输出HTML时目录为 _static )

图像的大小选项 (width 及 height) : 如果没有单位或单位为像素, 给定的尺寸信息仅在输出通道支持像素时才有用 ( 如输出LaTeX 没用). 其他单位在输出(如 pt )HTML、LaTeX 时被用到.

Sphinx 延伸了标准的文档化行为，只需在后面加星号:

.. image:: gnu.*

上面这样写，Sphinx 会搜索所有名字匹配的图像，而不管图像类型. 每个生成器则会选择最合适的图像. 一般，在源文件目录里文件名 gnu.* 会含有两个文件 gnu.pdf 和 gnu.png , LaTeX 生成器会选择前者，而HTML 生成器则匹配后者.

尾注

尾注 (:duref:`ref <footnotes>`), 使用 [#name]_ 标记尾注的位置, 尾注的内容则在文档底部红色标题”Footnotes”的后面 , 如下:

Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_

.. rubric:: Footnotes

.. [#f1] 第一条尾注的文本.
.. [#f2] 第二条尾注的文本.

你也可以使用数字尾注 ([1]_) 或使用自动排序的([#]_).

引用

支持标准的reST 引用 (:duref:`ref <citations>`) , 且新增了”global”特性, 所有参考文献不受所在文件的限制. 如:

Lorem ipsum [Ref]_ dolor sit amet.

.. [Ref] 参考文献, 书,URL 等.

引用的使用同尾注很相近，但是它们没有数字标签或以 # 开始.

替换

reST 支持替换 “substitutions” (:duref:`ref <substitution-definitions>`), 有一小段文本或标记被关联到 |name|. 定义与尾注一样需有明确的标记块，如下:

.. |name| replace:: replacement *text*

或者:

.. |caution| image:: warning.png
             :alt: Warning!

详情查看 :duref:`reST reference for substitutions <substitution-definitions>` .

如果想在所有文档中使用这些替换, 需把它们放在 :confval:`rst_prolog` 或一个单独文件里， 然后在使用它们的文档文件里包含这个文件，包含指令 include . (请给出包含文件的扩展名，已区别于其他的源文件，避免Sphinx将其作为独立的文档文件.)

Sphinx 定义了一些默认的替换, 请查看 替换.

评论

有明确标记块但又不是有效的结构标记的标记 (像上面的尾注）都被视为评论 (:duref:`ref <comments>`). 例如:

.. 这是一个评论.

可以通过缩进产生多行评论:

..
   这整个缩进块都是
   一个评论.

   仍是一个评论.

源编码

在reST使用Unicode字符可以容易的包含特殊字符如破折号，版权标志. Sphinx 默认源文件使用UTF-8 编码; 你可以通过 :confval:`source_encoding` 的配置值改变编码.

常见问题

具体使用中可能会遇到一些问题:

• 内联标记的分离 如上面所讲，内联标记需与周围的文本使用空格分隔, 内联标记内部则使用反斜线转义空格. 查看详情: the reference .
• 内联标记不能嵌套 像这样写 *see :func:`foo`* 是不允许的.

Footnotes

What is a Domain?

Originally, Sphinx was conceived for a single project, the documentation of the Python language. Shortly afterwards, it was made available for everyone as a documentation tool, but the documentation of Python modules remained deeply built in – the most fundamental directives, like function, were designed for Python objects. Since Sphinx has become somewhat popular, interest developed in using it for many different purposes: C/C++ projects, JavaScript, or even reStructuredText markup (like in this documentation).

While this was always possible, it is now much easier to easily support documentation of projects using different programming languages or even ones not supported by the main Sphinx distribution, by providing a domain for every such purpose.

A domain is a collection of markup (reStructuredText directives and roles) to describe and link to objects belonging together, e.g. elements of a programming language. Directive and role names in a domain have names like domain:name, e.g. py:function. Domains can also provide custom indices (like the Python Module Index).

Having domains means that there are no naming problems when one set of documentation wants to refer to e.g. C++ and Python classes. It also means that extensions that support the documentation of whole new languages are much easier to write.

This section describes what the domains that come with Sphinx provide. The domain API is documented as well, in the section Domain API.

Basic Markup

Most domains provide a number of object description directives, used to describe specific objects provided by modules. Each directive requires one or more signatures to provide basic information about what is being described, and the content should be the description. The basic version makes entries in the general index; if no index entry is desired, you can give the directive option flag :noindex:. An example using a Python domain directive:

.. py:function:: spam(eggs)
                 ham(eggs)

   Spam or ham the foo.

This describes the two Python functions spam and ham. (Note that when signatures become too long, you can break them if you add a backslash to lines that are continued in the next line. Example:

.. py:function:: filterwarnings(action, message='', category=Warning, \
                                module='', lineno=0, append=False)
   :noindex:

(This example also shows how to use the :noindex: flag.)

The domains also provide roles that link back to these object descriptions. For example, to link to one of the functions described in the example above, you could say

The function :py:func:`spam` does a similar thing.

As you can see, both directive and role names contain the domain name and the directive name.

Default Domain

To avoid having to writing the domain name all the time when you e.g. only describe Python objects, a default domain can be selected with either the config value :confval:`primary_domain` or this directive:

.. default-domain:: name

Select a new default domain. While the :confval:`primary_domain` selects a global default, this only has an effect within the same file.

If no other default is selected, the Python domain (named py) is the default one, mostly for compatibility with documentation written for older versions of Sphinx.

Directives and roles that belong to the default domain can be mentioned without giving the domain name, i.e.

.. function:: pyfunc()

   Describes a Python function.

Reference to :func:`pyfunc`.

The Python Domain

The Python domain (name py) provides the following directives for module declarations:

.. py:module:: name

This directive marks the beginning of the description of a module (or package submodule, in which case the name should be fully qualified, including the package name). It does not create content (like e.g. py:class does).

This directive will also cause an entry in the global module index.

The platform option, if present, is a comma-separated list of the platforms on which the module is available (if it is available on all platforms, the option should be omitted). The keys are short identifiers; examples that are in use include “IRIX”, “Mac”, “Windows”, and “Unix”. It is important to use a key which has already been used when applicable.

The synopsis option should consist of one sentence describing the module’s purpose – it is currently only used in the Global Module Index.

The deprecated option can be given (with no value) to mark a module as deprecated; it will be designated as such in various locations then.

.. py:currentmodule:: name

This directive tells Sphinx that the classes, functions etc. documented from here are in the given module (like py:module), but it will not create index entries, an entry in the Global Module Index, or a link target for py:mod. This is helpful in situations where documentation for things in a module is spread over multiple files or sections – one location has the py:module directive, the others only py:currentmodule.

The following directives are provided for module and class contents:

.. py:data:: name

Describes global data in a module, including both variables and values used as “defined constants.” Class and object attributes are not documented using this environment.

.. py:exception:: name

Describes an exception class. The signature can, but need not include parentheses with constructor arguments.

.. py:function:: name(signature)

Describes a module-level function. The signature should include the parameters, enclosing optional parameters in brackets. Default values can be given if it enhances clarity; see Python Signatures. For example:

.. py:function:: Timer.repeat([repeat=3[, number=1000000]])

Object methods are not documented using this directive. Bound object methods placed in the module namespace as part of the public interface of the module are documented using this, as they are equivalent to normal functions for most purposes.

The description should include information about the parameters required and how they are used (especially whether mutable objects passed as parameters are modified), side effects, and possible exceptions. A small example may be provided.

.. py:class:: name[(signature)]

Describes a class. The signature can include parentheses with parameters which will be shown as the constructor arguments. See also Python Signatures.

Methods and attributes belonging to the class should be placed in this directive’s body. If they are placed outside, the supplied name should contain the class name so that cross-references still work. Example:

.. py:class:: Foo
   .. py:method:: quux()

-- or --

.. py:class:: Bar

.. py:method:: Bar.quux()

The first way is the preferred one.

.. py:attribute:: name

Describes an object data attribute. The description should include information about the type of the data to be expected and whether it may be changed directly.

.. py:method:: name(signature)

Describes an object method. The parameters should not include the self parameter. The description should include similar information to that described for function. See also Python Signatures.

.. py:staticmethod:: name(signature)

Like py:method, but indicates that the method is a static method.

New in version 0.4.

.. py:classmethod:: name(signature)

Like py:method, but indicates that the method is a class method.

New in version 0.6.

.. py:decorator:: name

.. py:decorator:: name(signature)

Describes a decorator function. The signature should not represent the signature of the actual function, but the usage as a decorator. For example, given the functions

def removename(func):
    func.__name__ = ''
    return func

def setnewname(name):
    def decorator(func):
        func.__name__ = name
        return func
    return decorator

the descriptions should look like this:

.. py:decorator:: removename

   Remove name of the decorated function.

.. py:decorator:: setnewname(name)

   Set name of the decorated function to *name*.

There is no py:deco role to link to a decorator that is marked up with this directive; rather, use the py:func role.

.. py:decoratormethod:: name

.. py:decoratormethod:: name(signature)

Same as py:decorator, but for decorators that are methods.

Refer to a decorator method using the py:meth role.

.. py:function:: compile(source[, filename[, symbol]])

.. py:function:: compile(source[, filename, symbol])

.. py:function:: compile(source : string[, filename, symbol]) -> ast object

.. py:function:: format_exception(etype, value, tb[, limit=None])

   Format the exception with a traceback.

   :param etype: exception type
   :param value: exception value
   :param tb: traceback object
   :param limit: maximum number of stack frames to show
   :type limit: integer or None
   :rtype: list of strings

:param integer limit: maximum number of stack frames to show

The C Domain

The C domain (name c) is suited for documentation of C API.

.. c:function:: type name(signature)

Describes a C function. The signature should be given as in C, e.g.:

.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

This is also used to describe function-like preprocessor macros. The names of the arguments should be given so they may be used in the description.

Note that you don’t have to backslash-escape asterisks in the signature, as it is not parsed by the reST inliner.

.. c:member:: type name

Describes a C struct member. Example signature:

.. c:member:: PyObject* PyTypeObject.tp_bases

The text of the description should include the range of values allowed, how the value should be interpreted, and whether the value can be changed. References to structure members in text should use the member role.

.. c:macro:: name

Describes a “simple” C macro. Simple macros are macros which are used for code expansion, but which do not take arguments so cannot be described as functions. This is not to be used for simple constant definitions. Examples of its use in the Python documentation include PyObject_HEAD and Py_BEGIN_ALLOW_THREADS.

.. c:type:: name

Describes a C type (whether defined by a typedef or struct). The signature should just be the type name.

.. c:var:: type name

Describes a global C variable. The signature should include the type, such as:

.. c:var:: PyObject* PyClass_Type

The C++ Domain

The C++ domain (name cpp) supports documenting C++ projects.

The following directives are available:

.. cpp:class:: signatures

.. cpp:function:: signatures

.. cpp:member:: signatures

.. cpp:type:: signatures

Describe a C++ object. Full signature specification is supported – give the signature as you would in the declaration. Here some examples:

.. cpp:function:: bool namespaced::theclass::method(int arg1, std::string arg2)

   Describes a method with parameters and types.

.. cpp:function:: bool namespaced::theclass::method(arg1, arg2)

   Describes a method without types.

.. cpp:function:: const T &array<T>::operator[]() const

   Describes the constant indexing operator of a templated array.

.. cpp:function:: operator bool() const

   Describe a casting operator here.

.. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept

   Describe a constexpr function here.

.. cpp:member:: std::string theclass::name

.. cpp:member:: std::string theclass::name[N][M]

.. cpp:type:: theclass::const_iterator

Will be rendered like this:

bool namespaced::theclass::method(int arg1, std::string arg2)

Describes a method with parameters and types.

bool namespaced::theclass::method(arg1, arg2)

Describes a method without types.

template<>
const T &array<T>::operator[]() const

Describes the constant indexing operator of a templated array.

operator bool() const

Describe a casting operator here.

constexpr void foo(std::string &bar[2]) noexcept

Describe a constexpr function here.

std::string theclass::name

std::string theclass::name[N][M]

type theclass::const_iterator

.. cpp:namespace:: namespace

Select the current C++ namespace for the following objects.

These roles link to the given object types:

:cpp:class:

:cpp:func:

:cpp:member:

:cpp:type:

Reference a C++ object. You can give the full signature (and need to, for overloaded functions.)

Note

Sphinx’ syntax to give references a custom title can interfere with linking to template classes, if nothing follows the closing angle bracket, i.e. if the link looks like this: :cpp:class:`MyClass<T>`. This is interpreted as a link to T with a title of MyClass. In this case, please escape the opening angle bracket with a backslash, like this: :cpp:class:`MyClass\<T>`.

The Standard Domain

The so-called “standard” domain collects all markup that doesn’t warrant a domain of its own. Its directives and roles are not prefixed with a domain name.

The standard domain is also where custom object descriptions, added using the add_object_type() API, are placed.

There is a set of directives allowing documenting command-line programs:

.. option:: name args, name args, ...

Describes a command line option or switch. Option argument names should be enclosed in angle brackets. Example:

.. option:: -m <module>, --module <module>

   Run a module as a script.

The directive will create a cross-reference target named after the first option, referencable by option (in the example case, you’d use something like :option:`-m`).

.. envvar:: name

Describes an environment variable that the documented code or program uses or defines. Referencable by envvar.

.. program:: name

Like py:currentmodule, this directive produces no output. Instead, it serves to notify Sphinx that all following option directives document options for the program called name.

If you use program, you have to qualify the references in your option roles by the program name, so if you have the following situation

.. program:: rm

.. option:: -r

   Work recursively.

.. program:: svn

.. option:: -r revision

   Specify the revision to work upon.

then :option:`rm -r` would refer to the first option, while :option:`svn -r` would refer to the second one.

The program name may contain spaces (in case you want to document subcommands like svn add and svn commit separately).

New in version 0.5.

There is also a very generic object description directive, which is not tied to any domain:

.. describe:: text

.. object:: text

This directive produces the same formatting as the specific ones provided by domains, but does not create index entries or cross-referencing targets. Example:

.. describe:: PAPER

   You can set this variable to select a paper size.

The JavaScript Domain

The JavaScript domain (name js) provides the following directives:

.. js:function:: name(signature)

Describes a JavaScript function or method. If you want to describe arguments as optional use square brackets as documented for Python signatures.

You can use fields to give more details about arguments and their expected types, errors which may be thrown by the function, and the value being returned:

.. js:function:: $.getJSON(href, callback[, errback])

   :param string href: An URI to the location of the resource.
   :param callback: Get's called with the object.
   :param errback:
       Get's called in case the request fails. And a lot of other
       text so we need multiple lines
   :throws SomeError: For whatever reason in that case.
   :returns: Something

This is rendered as:

$.getJSON(href, callback[, errback])

Arguments:	href (string) – An URI to the location of the resource. callback – Get’s called with the object. errback – Get’s called in case the request fails. And a lot of other text so we need multiple lines.
Throws:	SomeError – For whatever reason in that case.
Returns:	Something

.. js:class:: name

Describes a constructor that creates an object. This is basically like a function but will show up with a class prefix:

.. js:class:: MyAnimal(name[, age])

   :param string name: The name of the animal
   :param number age: an optional age for the animal

This is rendered as:

class MyAnimal(name[, age])

Arguments:	name (string) – The name of the animal age (number) – an optional age for the animal

.. js:data:: name

Describes a global variable or constant.

.. js:attribute:: object.name

Describes the attribute name of object.

These roles are provided to refer to the described objects:

:js:func:

:js:class:

:js:data:

:js:attr:

The reStructuredText domain

The reStructuredText domain (name rst) provides the following directives:

.. rst:directive:: name

Describes a reST directive. The name can be a single directive name or actual directive syntax (.. prefix and :: suffix) with arguments that will be rendered differently. For example:

.. rst:directive:: foo

   Foo description.

.. rst:directive:: .. bar:: baz

   Bar description.

will be rendered as:

.. foo::

Foo description.

.. bar:: baz

Bar description.

.. rst:role:: name

Describes a reST role. For example:

.. rst:role:: foo

   Foo description.

will be rendered as:

:foo:

Foo description.

These roles are provided to refer to the described objects:

:rst:dir:

:rst:role:

More domains

The sphinx-contrib repository contains more domains available as extensions; currently a Ruby and an Erlang domain.

Serialization builder details

All serialization builders outputs one file per source file and a few special files. They also copy the reST source files in the directory _sources under the output directory.

The PickleHTMLBuilder is a builtin subclass that implements the pickle serialization interface.

The files per source file have the extensions of out_suffix, and are arranged in directories just as the source files are. They unserialize to a dictionary (or dictionary like structure) with these keys:

body

The HTML “body” (that is, the HTML rendering of the source file), as rendered by the HTML translator.

title

The title of the document, as HTML (may contain markup).

toc

The table of contents for the file, rendered as an HTML <ul>.

display_toc

A boolean that is True if the toc contains more than one entry.

current_page_name

The document name of the current file.

parents, prev and next

Information about related chapters in the TOC tree. Each relation is a dictionary with the keys link (HREF for the relation) and title (title of the related document, as HTML). parents is a list of relations, while prev and next are a single relation.

sourcename

The name of the source file under _sources.

The special files are located in the root output directory. They are:

SerializingHTMLBuilder.globalcontext_filename

A pickled dict with these keys:

project, copyright, release, version

The same values as given in the configuration file.

style

:confval:`html_style`.

last_updated

Date of last build.

builder

Name of the used builder, in the case of pickles this is always 'pickle'.

titles

A dictionary of all documents’ titles, as HTML strings.

SerializingHTMLBuilder.searchindex_filename

An index that can be used for searching the documentation. It is a pickled list with these entries:

• A list of indexed docnames.
• A list of document titles, as HTML strings, in the same order as the first list.
• A dict mapping word roots (processed by an English-language stemmer) to a list of integers, which are indices into the first list.

environment.pickle

The build environment. This is always a pickle file, independent of the builder and a copy of the environment that was used when the builder was started.

Unlike the other pickle files this pickle file requires that the sphinx package is available on unpickling.

General configuration

Project information

Options for internationalization

These options influence Sphinx’ Native Language Support. See the documentation on Internationalization for details.

Options for HTML output

These options influence HTML as well as HTML Help output, and other builders that use Sphinx’ HTMLWriter class.

Options for epub output

These options influence the epub output. As this builder derives from the HTML builder, the HTML options also apply where appropriate. The actual values for some of the options is not really important, they just have to be entered into the Dublin Core metadata.

Options for LaTeX output

These options influence LaTeX output.

Options for text output

These options influence text output.

Options for manual page output

These options influence manual page output.

Options for Texinfo output

These options influence Texinfo output.

Options for the linkcheck builder

Footnotes

Using a theme

Using an existing theme is easy. If the theme is builtin to Sphinx, you only need to set the :confval:`html_theme` config value. With the :confval:`html_theme_options` config value you can set theme-specific options that change the look and feel. For example, you could have the following in your conf.py:

html_theme = "default"
html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

That would give you the default theme, but with a sidebar on the right side and a black background for the relation bar (the bar with the navigation links at the page’s top and bottom).

If the theme does not come with Sphinx, it can be in two forms: either a directory (containing theme.conf and other needed files), or a zip file with the same contents. Either of them must be put where Sphinx can find it; for this there is the config value :confval:`html_theme_path`. It gives a list of directories, relative to the directory containing conf.py, that can contain theme directories or zip files. For example, if you have a theme in the file blue.zip, you can put it right in the directory containing conf.py and use this configuration:

html_theme = "blue"
html_theme_path = ["."]

Builtin themes

Sphinx comes with a selection of themes to choose from.

These themes are:

• basic – This is a basically unstyled layout used as the base for the other themes, and usable as the base for custom themes as well. The HTML contains all important elements like sidebar and relation bar. There are these options (which are inherited by the other themes):

  • nosidebar (true or false): Don’t include the sidebar. Defaults to false.
  • sidebarwidth (an integer): Width of the sidebar in pixels. (Do not include px in the value.) Defaults to 230 pixels.

• default – This is the default theme, which looks like the Python documentation. It can be customized via these options:

  • rightsidebar (true or false): Put the sidebar on the right side. Defaults to false.
  • stickysidebar (true or false): Make the sidebar “fixed” so that it doesn’t scroll out of view for long body content. This may not work well with all browsers. Defaults to false.
  • collapsiblesidebar (true or false): Add an experimental JavaScript snippet that makes the sidebar collapsible via a button on its side. Doesn’t work together with “rightsidebar” or “stickysidebar”. Defaults to false.
  • externalrefs (true or false): Display external links differently from internal links. Defaults to false.

  There are also various color and font options that can change the color scheme without having to write a custom stylesheet:

  • footerbgcolor (CSS color): Background color for the footer line.
  • footertextcolor (CSS color): Text color for the footer line.
  • sidebarbgcolor (CSS color): Background color for the sidebar.
  • sidebarbtncolor (CSS color): Background color for the sidebar collapse button (used when collapsiblesidebar is true).
  • sidebartextcolor (CSS color): Text color for the sidebar.
  • sidebarlinkcolor (CSS color): Link color for the sidebar.
  • relbarbgcolor (CSS color): Background color for the relation bar.
  • relbartextcolor (CSS color): Text color for the relation bar.
  • relbarlinkcolor (CSS color): Link color for the relation bar.
  • bgcolor (CSS color): Body background color.
  • textcolor (CSS color): Body text color.
  • linkcolor (CSS color): Body link color.
  • visitedlinkcolor (CSS color): Body color for visited links.
  • headbgcolor (CSS color): Background color for headings.
  • headtextcolor (CSS color): Text color for headings.
  • headlinkcolor (CSS color): Link color for headings.
  • codebgcolor (CSS color): Background color for code blocks.
  • codetextcolor (CSS color): Default text color for code blocks, if not set differently by the highlighting style.
  • bodyfont (CSS font-family): Font for normal text.
  • headfont (CSS font-family): Font for headings.

• sphinxdoc – The theme used for this documentation. It features a sidebar on the right side. There are currently no options beyond nosidebar and sidebarwidth.

• scrolls – A more lightweight theme, based on the Jinja documentation. The following color options are available:

  • headerbordercolor
  • subheadlinecolor
  • linkcolor
  • visitedlinkcolor
  • admonitioncolor

• agogo – A theme created by Andi Albrecht. The following options are supported:

  • bodyfont (CSS font family): Font for normal text.
  • headerfont (CSS font family): Font for headings.
  • pagewidth (CSS length): Width of the page content, default 70em.
  • documentwidth (CSS length): Width of the document (without sidebar), default 50em.
  • sidebarwidth (CSS length): Width of the sidebar, default 20em.
  • bgcolor (CSS color): Background color.
  • headerbg (CSS value for “background”): background for the header area, default a grayish gradient.
  • footerbg (CSS value for “background”): background for the footer area, default a light gray gradient.
  • linkcolor (CSS color): Body link color.
  • headercolor1, headercolor2 (CSS color): colors for <h1> and <h2> headings.
  • headerlinkcolor (CSS color): Color for the backreference link in headings.
  • textalign (CSS text-align value): Text alignment for the body, default is justify.

• nature – A greenish theme. There are currently no options beyond nosidebar and sidebarwidth.

• pyramid – A theme from the Pyramid web framework project, designed by Blaise Laflamme. There are currently no options beyond nosidebar and sidebarwidth.

• haiku – A theme without sidebar inspired by the Haiku OS user guide. The following options are supported:

  • full_logo (true or false, default false): If this is true, the header will only show the :confval:`html_logo`. Use this for large logos. If this is false, the logo (if present) will be shown floating right, and the documentation title will be put in the header.
  • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS colors): Colors for various body elements.

• traditional – A theme resembling the old Python documentation. There are currently no options beyond nosidebar and sidebarwidth.

• epub – A theme for the epub builder. There are currently no options. This theme tries to save visual space which is a sparse resource on ebook readers.

Creating themes

As said, themes are either a directory or a zipfile (whose name is the theme name), containing the following:

• A theme.conf file, see below.
• HTML templates, if needed.
• A static/ directory containing any static files that will be copied to the output static directory on build. These can be images, styles, script files.

The theme.conf file is in INI format [1] (readable by the standard Python ConfigParser module) and has the following structure:

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename

[options]
variable = default value

• The inherit setting gives the name of a “base theme”, or none. The base theme will be used to locate missing templates (most themes will not have to supply most templates if they use basic as the base theme), its options will be inherited, and all of its static files will be used as well.
• The stylesheet setting gives the name of a CSS file which will be referenced in the HTML header. If you need more than one CSS file, either include one from the other via CSS’ @import, or use a custom HTML template that adds <link rel="stylesheet"> tags as necessary. Setting the :confval:`html_style` config value will override this setting.
• The pygments_style setting gives the name of a Pygments style to use for highlighting. This can be overridden by the user in the :confval:`pygments_style` config value.
• The options section contains pairs of variable names and default values. These options can be overridden by the user in :confval:`html_theme_options` and are accessible from all templates as theme_<name>.

Do I need to use Sphinx’ templates to produce HTML?

No. You have several other options:

• You can write a TemplateBridge subclass that calls your template engine of choice, and set the :confval:`template_bridge` configuration value accordingly.
• You can write a custom builder that derives from StandaloneHTMLBuilder and calls your template engine of choice.
• You can use the PickleHTMLBuilder that produces pickle files with the page contents, and postprocess them using a custom tool, or use them in your Web application.

Jinja/Sphinx Templating Primer

The default templating language in Sphinx is Jinja. It’s Django/Smarty inspired and easy to understand. The most important concept in Jinja is template inheritance, which means that you can overwrite only specific blocks within a template, customizing it while also keeping the changes at a minimum.

To customize the output of your documentation you can override all the templates (both the layout templates and the child templates) by adding files with the same name as the original filename into the template directory of the structure the Sphinx quickstart generated for you.

Sphinx will look for templates in the folders of :confval:`templates_path` first, and if it can’t find the template it’s looking for there, it falls back to the selected theme’s templates.

A template contains variables, which are replaced with values when the template is evaluated, tags, which control the logic of the template and blocks which are used for template inheritance.

Sphinx’ basic theme provides base templates with a couple of blocks it will fill with data. These are located in the themes/basic subdirectory of the Sphinx installation directory, and used by all builtin Sphinx themes. Templates with the same name in the :confval:`templates_path` override templates supplied by the selected theme.

For example, to add a new link to the template area containing related links all you have to do is to add a new template called layout.html with the following contents:

{% extends "!layout.html" %}
{% block rootrellink %}
    <li><a href="http://project.invalid/">Project Homepage</a> &raquo;</li>
    {{ super() }}
{% endblock %}

By prefixing the name of the overridden template with an exclamation mark, Sphinx will load the layout template from the underlying HTML theme.

Important: If you override a block, call {{ super() }} somewhere to render the block’s content in the extended template – unless you don’t want that content to show up.

Working with the builtin templates

The builtin basic theme supplies the templates that all builtin Sphinx themes are based on. It has the following elements you can override or use:

{% extends "!layout.html" %}
{% set reldelim1 = ' >' %}

Builtin Sphinx extensions

These extensions are built in and can be activated by respective entries in the :confval:`extensions` configuration value:

$ sphinx-autogen -o generated *.rst

sphinx.util.relative_uri
========================

.. autofunction:: sphinx.util.relative_uri

The parrot module
=================

.. testsetup:: *

   import parrot

The parrot module is a module about parrots.

Doctest example:

.. doctest::

   >>> parrot.voom(3000)
   This parrot wouldn't voom if you put 3000 volts through it!

Test-Output example:

.. testcode::

   parrot.voom(3000)

This would output:

.. testoutput::

   This parrot wouldn't voom if you put 3000 volts through it!

Third-party extensions

You can find several extensions contributed by users in the Sphinx Contrib repository. It is open for anyone who wants to maintain an extension publicly; just send a short message asking for write permissions.

There are also several extensions hosted elsewhere. The Wiki at BitBucket maintains a list of those.

If you write an extension that you think others will find useful or you think should be included as a part of Sphinx, please write to the project mailing list (join here).

import sys, os

sys.path.append(os.path.abspath('exts'))

extensions = ['foo']