Sphinx 常见问题¶

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

我如何...¶

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

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

将 Sphinx 与... 一起使用¶

Read the Docs

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

Epydoc

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

Doxygen

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 命令，可以自动将 Sphinx 文档上传到 PyPI 包文档区域 https://pythonhosted.org/。

GitHub Pages

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

MediaWiki

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

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 搜索

要用 Google 搜索替换 Sphinx 的内置搜索功能，请按以下步骤操作

转到 https://#/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.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 vs. Docutils¶

太长不看：docutils 将 reStructuredText 转换为多种输出格式。Sphinx 基于 docutils 构建，以允许构建交叉引用和索引的文档主体。

docutils 是一个文本处理系统，用于将纯文本文档转换为其他更丰富的格式。正如 docutils 文档中指出的那样，docutils 使用 读取器 读取文档，解析器 将纯文本格式解析为由不同类型的节点组成的内部树表示，以及 写入器 以各种文档格式输出此树。docutils 为一种纯文本格式——reStructuredText——提供了解析器，尽管已经实现了其他 非树内 解析器，包括 Sphinx 的Markdown 解析器。另一方面，它为许多不同的格式提供了写入器，包括 HTML、LaTeX、man 页面、开放文档格式和 XML。

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

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

Epub 信息¶

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

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

您可能需要稍作尝试才能获得合理的结果。
测试创建的 epubs。您可以使用几种替代方案。我所知道的有 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 使用 Info-hide-note-references 的 hide 值显示 Sphinx 生成的 Info 文件，并对所有其他 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
```