Sphinx常见问题解答¶

这是关于Sphinx的常见问题列表。欢迎提出新的建议！

我该如何...¶

不用LaTeX创建pdf文件？: rinohtype 提供了一个PDF构建器，可以作为LaTeX构建器的直接替代品。
获取到节的数目？: 它们在LaTeX输出中是自动的；对于HTML，为 toctree 指令，从中开始编号。
... 自定义生成的HTML文件的外观？: 使用主题，请参阅 HTML主题。
... 添加全局替换或包含？: 将它们添加到 rst_prolog 或 rst_epilog 配置值中。
... 在侧边栏中显示整个目录树？: 在自定义布局模板中使用可调用的 toctree，可能在 sidebartoc 块中。
... 编写我自己的插件?: 请参阅教程。
... 使用MoinMoin标记从现有文档转换？: 最简单的方法是转换为xhtml，然后转换 xhtml to reStructuredText 。您仍然需要标记类等，但标题和代码示例会干净地出现。

有关更多插件和其他贡献的内容，请参阅 sphinx-contrib 存储库。

Sphinx拍档...¶

阅读文档

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

Epy文档

有一个第三方插件提供了一个 api role ，它引用给定标识符的Epydoc的api文档。

编程辅助工具

Michael Jones开发了一个reStructuredText/Sphinx桥接到doxygen，称为 breathe 。

SCons

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

PyPI

Jannis Leidel编写了一个 setuptools command 它会自动将Sphinx文档上载到位于的PyPI包文档区域 https://pythonhosted.org/。

GitHub页面

请添加 sphinx.ext.githubpages 到你的项目。它允许您在GitHub页面中发布文档。它在自动生成HTML文档时为GitHub页面生成帮助文件。

维基百科

请参阅 sphinx-wiki，这是由 Kevin Dunn 开发的项目。

谷歌分析

你可以使用自定义 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 %}

谷歌搜索

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

去 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¶

tl;dr: docutils 将reStructedText转换为多种输出格式。Sphinx构建在docutils之上，允许构建交叉引用和索引的文档体。

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

docutils通过一系列 front-end tools 公开其所有功能，例如“rst2html”、“rst2odt”和“rst2xml”。但最关键的是，所有这些工具和docutil本身都与单个文档有关。文档的层次结构通常不支持文档的交叉引用。

Sphinx通过利用docutils的读取器和解析器并提供自己的构建器，在docutils的基础上构建。因此，Sphinx包装了docutils提供的一些 writers 。这使得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/ 目录，并删除float设置。
必须手动包含在 toctree 指令之外插入的文件。这有时适用于附录，例如术语表或索引。您可以使用 epub_post_files 选项添加它们。
epub封面页的处理不同于reStructedText过程，后者自动解析图像路径并将图像放入 _images 目录。对于epub封面页，请将图像放在 html_static_path 目录中，并在 epub_cover config选项中引用它的完整路径。
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 和gnuemacs。info 程序的功能较少，但在大多数Unix环境中都可用，并且可以从终端快速访问。Emacs提供了更好的字体和颜色显示，并支持广泛的定制（当然）。

展示链接¶

在使用生成的信息文件时，您可能会遇到一个值得注意的问题，即引用的显示方式。如果您读取信息文件的源代码，对该节的引用将如下所示：

* note Displaying Links: target-id

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

展示链接

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

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

如果希望Emacs显示Sphinx生成的信息文件，并使用 Info-hide-note-references 的 hide 值和所有其他信息文件的默认值，请尝试将以下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。
在菜单项和erefs中，冒号（ : ）不能正确转义。它们将被替换为分号（ ; ）。
可以使用某种正式的URI方案 Info 创建指向外部信息文件的链接。例如:
```
info:Texinfo#makeinfo_options
```