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 role，它引用了给定标识符的 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

请参阅 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 搜索

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

  1. 转到 https://cse.google.com/cse/all 创建 Google 搜索代码片段。

  2. 复制代码片段并将其粘贴到您的 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>

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

Sphinx 与 Docutils

总结：docutils 将 reStructuredText 转换为多种输出格式。Sphinx 构建在 docutils 之上，以允许构建交叉引用和索引的文档主体。

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

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

Sphinx 通过利用 docutils 的 readers 和 parsers 并提供其自己的 Builders 构建在 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/ 目录，并删除浮动设置。

  • 在 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 提供更好的字体和颜色显示，并支持广泛的自定义（当然）。

注释

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

  • 每个节对应于 Info 文件中的不同 node。

  • 冒号 (:) 无法在菜单条目和交叉引用中正确转义。它们将被替换为分号 (;)。

  • 可以使用半官方 URI 方案 info 创建指向外部 Info 文件的链接。例如

    info:Texinfo#makeinfo_options