Sphinx 常见问题解答¶

这是一个关于 Sphinx 的常见问题解答列表。欢迎您提出新的条目！

如何…¶

… 在没有 LaTeX 的情况下创建 PDF 文件？: rinohtype 提供了一个 PDF 构建器，可以作为 LaTeX 构建器的替代品。
… 获取章节编号？: 在 LaTeX 输出中它们是自动的；对于 HTML，在您想要开始编号的 toctree 指令中提供 :numbered: 选项。
… 自定义构建的 HTML 文件的外观？: 使用主题，请参阅 HTML 主题。
… 添加全局替换或包含？: 在 rst_prolog 或 rst_epilog 配置值中添加它们。
… 在侧边栏中显示整个 TOC 树？: 在自定义布局模板中使用 toctree 可调用函数，可能在 sidebartoc 块中。
… 编写我自己的扩展？: 请参阅教程。
… 使用 MoinMoin 标记从我现有的文档中转换？: 最简单的方法是转换为 xhtml，然后将 xhtml 转换为 reStructuredText。您仍然需要标记类等，但标题和代码示例会清晰地显示出来。

更多扩展和其他贡献内容，请参阅 sphinx-contrib 存储库。

使用 Sphinx 与…¶

Read the Docs

Read the Docs 是一个基于 Sphinx 的文档托管服务。他们将托管 sphinx 文档，以及支持许多其他功能，包括版本支持、PDF 生成等等。入门指南是一个很好的起点。

Epydoc

有一个第三方扩展提供了一个 api 角色，它引用了给定标识符的 Epydoc API 文档。

Doxygen

Michael Jones 开发了一个名为 breathe 的 reStructuredText/Sphinx 桥接 Doxygen。

SCons

Glenn Hutchings 编写了一个 SCons 构建脚本用于构建 Sphinx 文档；它托管在这里： https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html

PyPI

Jannis Leidel 编写了一个 setuptools 命令，它会自动将 Sphinx 文档上传到 https://pythonhosted.org/ 上的 PyPI 包文档区域。

GitHub Pages

请将 sphinx.ext.githubpages 添加到您的项目中。它允许您在 GitHub Pages 上发布您的文档。它在构建 HTML 文档时自动生成 GitHub Pages 的辅助文件。

MediaWiki

请参阅 sphinx-wiki，Kevin Dunn 的一个项目。

Google Analytics

您可以使用自定义的 layout.html 模板，如下所示

{% extends "!layout.html" %}

{%- block extrahead %}
{{ super() }}
<script>
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'XXX account number XXX']);
  _gaq.push(['_trackPageview']);
</script>
{% endblock %}

{% block footer %}
{{ super() }}
<div class="footer">This page uses <a href="https://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script>
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'https://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>
{% endblock %}

Google 搜索

要将 Sphinx 的内置搜索功能替换为 Google 搜索，请执行以下操作

访问 https://cse.google.com/cse/all 创建 Google 搜索代码片段。

复制代码片段并将其粘贴到 Sphinx 项目中的 _templates/searchbox.html 中

<div>
   <h3>{{ _('Quick search') }}</h3>
   <script>
      (function() {
         var cx = '......';
         var gcse = document.createElement('script');
         gcse.async = true;
         gcse.src = 'https://cse.google.com/cse.js?cx=' + cx;
         var s = document.getElementsByTagName('script')[0];
         s.parentNode.insertBefore(gcse, s);
      })();
   </script>
  <gcse:search></gcse:search>
</div>

将 searchbox.html 添加到 html_sidebars 配置值中。

Sphinx 与 Docutils 的比较¶

简而言之：docutils 将 reStructuredText 转换为多种输出格式。Sphinx 基于 docutils，允许构建交叉引用和索引的文档主体。

docutils 是一种文本处理系统，用于将纯文本文档转换为其他更丰富的格式。如 docutils 文档中所述，docutils 使用读取器读取文档，解析器将纯文本格式解析为由不同类型节点组成的内部树表示，以及编写器以各种文档格式输出此树。docutils 为一种纯文本格式提供了解析器 - reStructuredText - 尽管已经实现了其他树外解析器，包括 Sphinx 的 Markdown 解析器。另一方面，它为许多不同的格式提供了编写器，包括 HTML、LaTeX、手册页、Open Document Format 和 XML。

docutils 通过各种前端工具公开其所有功能，例如 rst2html、rst2odt 和 rst2xml。但至关重要的是，所有这些工具以及 docutils 本身都与单个文档有关。它们不支持诸如交叉引用、文档索引或文档层次结构构建（通常在目录中体现）等概念。

Sphinx 通过利用 docutils 的读取器和解析器并提供自己的构建器来构建于 docutils 之上。因此，Sphinx 包装了 docutils 提供的一些编写器。这使得 Sphinx 能够提供许多使用 docutils 根本无法实现的功能，例如上面概述的功能。

Epub 信息¶

以下列表提供了一些关于创建 epub 文件的提示

将文本分成几个文件。各个 HTML 文件越长，电子书阅读器呈现它们所需的时间就越长。在极端情况下，渲染可能需要长达一分钟。
尽量减少标记。这也有助于缩短渲染时间。
对于某些阅读器，您可以使用嵌入式或外部字体，使用 CSS @font-face 指令。这对于代码列表非常有用，因为代码列表通常在右侧边距处被截断。默认的 Courier 字体（或变体）相当宽，您每行只能显示最多 60 个字符。如果您将其替换为更窄的字体，则可以每行显示更多字符。您甚至可以使用 FontForge 创建某些免费字体的窄变体。在我的例子中，我每行可以显示多达 70 个字符。

您可能需要进行一些实验才能获得合理的结果。
测试创建的 epub 文件。您可以使用多种替代方案。我所知道的包括 Epubcheck、Calibre、FBreader（尽管它不渲染 CSS）和 Bookworm。对于 Bookworm，您可以从 https://code.google.com/archive/p/threepress 下载源代码并运行您自己的本地服务器。
大型浮动 div 未正确显示。如果它们覆盖了多个页面，则 div 仅显示在第一页上。在这种情况下，您可以将 epub.css 从 sphinx/themes/epub/static/ 目录复制到您本地的 _static/ 目录中，并删除浮动设置。
在 toctree 指令之外插入的文件必须手动包含。这有时适用于附录，例如词汇表或索引。您可以使用 epub_post_files 选项添加它们。
epub 封面页的处理方式不同于 reStructuredText 程序，该程序会自动解析图像路径并将图像放入 _images 目录中。对于 epub 封面页，请将图像放在 html_static_path 目录中，并在 epub_cover 配置选项中使用其完整路径引用它。
kindlegen 命令可以将 epub3 生成的文件转换为 Kindle 的 .mobi 文件。执行以下命令后，您可以在 _build/epub 下获取 yourdoc.mobi
```
$ make epub
$ kindlegen _build/epub/yourdoc.epub
```
kindlegen 命令不接受包含 toctree 指令周围的章节标题的文档
```
Section Title
=============

.. toctree::

   subdocument

Section After Toc Tree
======================
```
kindlegen 假设所有文档的顺序都是线性的，但生成的文档对于 kindlegen 来说顺序很复杂
```
``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``
```
如果您收到以下错误，请修复您的文档结构
```
Error(prcgen):E24011: TOC section scope is not included in the parent chapter:(title)
Error(prcgen):E24001: The table of content could not be built.
```

Texinfo 信息¶

阅读 Info 文件主要有两个程序，info 和 GNU Emacs。 info 程序功能较少，但大多数 Unix 环境中都可用，并且可以从终端快速访问。Emacs 提供更好的字体和颜色显示，并支持广泛的自定义（当然）。

显示链接¶

在生成的 Info 文件中，您可能会遇到一个明显的难题，即引用的显示方式。如果您阅读 Info 文件的源代码，对本节的引用将如下所示：

* note Displaying Links: target-id

在独立阅读器 info 中，引用按其在源代码中的显示方式显示。另一方面，Emacs 默认会将 *note: 替换为 see 并隐藏 target-id。例如：

显示链接

可以通过 texinfo_cross_references 禁用文档中内联引用的生成。这使得 Info 文件更易于使用独立阅读器（info）阅读。

Emacs 显示引用的确切行为取决于变量 Info-hide-note-references。如果将其设置为 hide 值，Emacs 将隐藏 *note: 部分和 target-id。这通常是查看基于 Sphinx 的文档的最佳方法，因为它们经常使用链接并且没有考虑到此限制。但是，更改此变量会影响所有 Info 文档的显示方式，并且大多数文档都考虑到了此行为。

如果您希望 Emacs 使用 hide 值显示 Sphinx 生成的 Info 文件的 Info-hide-note-references，并对所有其他 Info 文件使用默认值，请尝试将以下 Emacs Lisp 代码添加到您的启动文件 ~/.emacs.d/init.el 中。

(defadvice info-insert-file-contents (after
                                      sphinx-info-insert-file-contents
                                      activate)
  "Hack to make `Info-hide-note-references' buffer-local and
automatically set to `hide' iff it can be determined that this file
was created from a Texinfo file generated by Docutils or Sphinx."
  (set (make-local-variable 'Info-hide-note-references)
       (default-value 'Info-hide-note-references))
  (save-excursion
    (save-restriction
      (widen) (goto-char (point-min))
      (when (re-search-forward
             "^Generated by \\(Sphinx\\|Docutils\\)"
             (save-excursion (search-forward "\x1f" nil t)) t)
        (set (make-local-variable 'Info-hide-note-references)
             'hide)))))

注释¶

如果您想创建 Texinfo 文件，以下注释可能会有所帮助：

每个部分对应 Info 文件中的一个不同的 node。
冒号（:）无法在菜单条目和交叉引用中正确转义。它们将被替换为分号（;）。
可以使用某种程度上官方的 URI 方案 info 创建指向外部 Info 文件的链接。例如：
```
info:Texinfo#makeinfo_options
```