开始使用¶
Sphinx 是一个 文档生成器 或者是一个将一组纯文本源文件转换为各种输出格式的工具,自动生成交叉引用、索引等.也就是说,如果您有一个目录包含一堆 reStructuredText 或 Markdown 文档,Sphinx 可以生成一系列 HTML 文件、一个 PDF 文件（通过 LaTeX）、手册页等等.
Sphinx 专注于文档,特别是手写文档,然而,Sphinx 也可以用于生成博客、主页甚至书籍.Sphinx 的许多强大功能源于其默认的纯文本标记格式 reStructuredText 的丰富性,以及其 显著的可扩展性能力 .
本文件的目标是让您快速了解 Sphinx 是什么以及您可能如何使用它.完成后,您可以查看 安装指南 ,然后了解 Sphinx 使用的默认标记格式 reStructuredText .
有关撰写文档的一般”介绍”——以及原因和方法,请参见由 Eric Holscher 撰写的 Write the docs.
设置文档源¶
Sphinx文档源的根目录称为 源目录 .此目录还包含Sphinx配置文件 conf.py ,在这里您可以配置Sphinx读取源文件和构建文档的各个方面.[#]_
Sphinx配备了一个名为:程序 :sphinx-quickstart 的脚本,它会设置一个源目录并创建一个默认的 conf.py ,其中包含根据你回答的一些问题生成的最有用的配置值.要使用此功能,请运行:
$ sphinx-quickstart
定义文档结构¶
假设你已经运行了 sphinx-quickstart .它创建了一个包含 conf.py 的源目录和一个根文档 index.rst . 根文档 的主要功能是作为欢迎页面,并包含 “目录树”（或 toctree）的根.这是 Sphinx 为 reStructuredText 添加的主要功能之一,是将多个文件连接到单一文档层次结构的一种方法.
reStructuredText 指令
toctree 是一个 reStructuredText 指令 ,这是一个非常多功能的标记.指令可以有参数、选项和内容.
*参数*直接在指令名称后的双冒号之后给出.每个指令决定是否可以有参数,以及参数的数量.
选项 以 “字段列表” 的形式在参数后给出. maxdepth 是 toctree 指令的一个选项.
内容 在空行之后跟随选项或参数.每个指令决定是否允许内容,以及如何处理它.
指令的一个常见问题是**内容的第一行必须与选项保持相同的缩进级别**.
toctree 指令最初是空的,格式如下:
.. toctree::
:maxdepth: 2
您可以在指令的 content 中列出要添加的文档:
.. toctree::
:maxdepth: 2
usage/installation
usage/quickstart
...
这就是本文件的 toctree 的确切样子.包含的文档被表示为 文档名称
,简而言之,这意味着你省略文件名扩展名,并使用正斜杠 ( / ) 作为目录分隔符.
参见
关于 toctree 指令 的更多信息,请阅读.
现在您可以创建在 toctree 中列出的文件并添加内容,它们的章节标题将被插入（最多到 maxdepth 级别）到 toctree 指令所在的位置.此外,Sphinx 现在了解您文档的顺序和层次结构.（它们可能包含 toctree 指令,这意味着如果需要,您可以创建深度嵌套的层次结构.）
添加内容¶
在Sphinx源文件中,您可以使用大多数标准的 reStructuredText 特性.Sphinx 还添加了一些额外功能.例如,您可以使用 ref 角色以便携的方式添加跨文件引用（适用于所有输出类型）.
例如,如果您正在查看HTML版本,可以查看此文档的源代码——请使用侧边栏中的”显示源代码”链接.
待处理
添加新指南时,请更新下面的链接.
参见
reStructuredText 以获取更深入的 reStructuredText 介绍,包括 Sphinx 添加的标记.
运行构建¶
现在您已经添加了一些文件和内容,让我们进行文档的第一次构建.构建是通过 sphinx-build 程序启动的:
$ sphinx-build -M html sourcedir outputdir
其中 sourcedir 是 源目录 ,而 outputdir 是您希望放置生成文档的目录. -M 选项选择一个构建器;在这个例子中,Sphinx 将构建 HTML 文件.
参见
有关 sphinx-build 支持的所有选项,请参阅 sphinx-build 手册页 .
然而,:program:sphinx-quickstart 脚本会创建一个 Makefile 和一个 make.bat ,使您的生活更加轻松.这些可以通过运行 make 加上构建器的名称来执行.例如.
$ make html
这将在您选择的构建目录中生成 HTML 文档.执行 make 而不加参数以查看可用的目标.
如何生成PDF文档?
make latexpdf 运行 LaTeX builder 并立即为您调用 pdfTeX 工具链.
待处理
将这整部分移入关于rST或指令的指南中
文档对象¶
Sphinx的主要目标之一是在任何:d受定义:领域 中轻松文档化:d受定义:对象 （在非常广义的意义上）.领域是属于一起的对象类型的集合,带有标记以创建和引用这些对象的描述.
最显著的领域是 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])¶
返回一个迭代器,该迭代器生成一个元组,包含*序列*的索引和项.（等等.）
该指令的参数是您描述的对象的 签名 ,内容是其文档.可以给出多个签名,每个签名占一行.
Python 域恰好是默认域,因此您不需要在标记前添加域名.
.. function:: enumerate(sequence[, start=0])
...
如果您保持默认域的默认设置,它完成的工作是相同的.
还有更多指令用于记录其他类型的Python对象,例如 py:class 或 py:method .每种对象类型还有一个交叉引用的 role .此标记将创建一个链接到 enumerate() 的文档.
The :py:func:`enumerate` function can be used for ...
这里是证明:一个指向 enumerate() 的链接.
再次,如果Python域是默认的,可以省略 py: .哪个文件包含 enumerate() 的实际文档并不重要;Sphinx会找到它并创建链接.
每个领域都会有关于签名如何显示的特殊规则,使格式化输出看起来美观,或者添加特定的功能,例如链接到参数类型,例如在C/C++领域中.
参见
域 提供所有可用的域及其指令/角色.
基本配置¶
早先我们提到过,:file:conf.py 文件控制着 Sphinx 如何处理你的文档.在该文件中,该文件作为 Python 源文件执行,你可以在其中分配配置值.对于高级用户:由于它是由 Sphinx 执行的,你可以在其中执行非平凡的任务,比如扩展 sys.path 或导入一个模块来查找你正在记录的版本.
您可能希望更改的配置值已经由 sphinx-quickstart 放入 conf.py 中,并且最初是被注释掉的（使用标准的 Python 语法: # 注释掉剩余的行）.要更改默认值,请删除井号并修改值.要自定义未由 sphinx-quickstart 自动添加的配置值,只需添加一个额外的赋值语句.
请注意,该文件使用Python语法表示字符串、数字、列表等.该文件默认以UTF-8编码保存,这在第一行的编码声明中有所说明.
参见
配置 用于所有可用配置值的文档.
待处理
将此整个文档移至不同部分
自动文档¶
在记录Python代码时,通常会在源文件中放置大量文档内容,称为文档字符串. Sphinx支持通过一个称为 autodoc 的 扩展 （扩展是一个Python模块,为Sphinx项目提供额外功能）来包含您模块中的文档字符串.
参见
sphinx.ext.autodoc 详细描述了autodoc的所有功能.
Intersphinx¶
许多 Sphinx 文档,包括 Python 文档 ,都在互联网上发布.当您想要从文档中链接到这些文档时,可以使用 sphinx.ext.intersphinx .
要使用intersphinx,您需要在:file:conf.py 中激活它,将字符串 'sphinx.ext.intersphinx' 放入:confval:extensions 列表中,并设置:confval:intersphinx_mapping 配置值.
例如,要在Python库手册中链接到 io.open() ,你需要设置你的 :confval :intersphinx_mapping ,如下所示:
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
现在,您可以写一个交叉引用,如``:py:func:io.open` .任何在当前文档集中没有匹配目标的交叉引用,将会在配置的 intersphinx_mapping 文档集中查找（这需要访问 URL 以下载有效目标的列表）.Intersphinx 也适用于其他一些 domain 的角色,包括 :ref: ,但不适用于 :doc: ,因为这不是领域角色.
参见
sphinx.ext.intersphinx 用于完整描述 intersphinx 的功能.
更多要涵盖的主题¶
脚注