Sphinx 常见问题解答¶

这是一个关于Sphinx的常见问题列表.欢迎提出新的条目!

我该怎么做…¶

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

对于更多扩展和其他贡献的内容,请参见 sphinx-contrib 仓库.

使用 Sphinx 与…¶

阅读文档

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

Epydoc

有一个第三方扩展提供了一个 api role ,它引用 Epydoc 的 API 文档以获取给定标识符.

Doxygen

Michael Jones 开发了一个名为 breathe 的 reStructuredText/Sphinx 与 doxygen 的桥梁.

SCons

Glenn Hutchings 编写了一个用于构建 Sphinx 文档的 SCons 构建脚本;它托管在这里: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的内置搜索功能,请按以下步骤操作:

前往 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 使用 readers 读取文档,*parsers* 将纯文本格式解析为内部树形表示,该表示由不同类型的 nodes 组成,以及 writers 以各种文档格式输出此树.docutils 提供了一种纯文本格式的解析器 - reStructuredText - 尽管其他 out-of-tree 解析器已被实现,包括 Sphinx 的 Markdown 解析器.另一方面,它提供了许多不同格式的 writers,包括 HTML、LaTeX、man pages、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 只会在第一页显示.在这种情况下,你可以从 sphinx/themes/epub/static/ 目录复制 epub.css 到你本地的 _static/ 目录并移除浮动设置.
在 toctree 指令之外插入的文件必须手动包含.这有时适用于附录,例如词汇表或索引.您可以使用 epub_post_files 选项添加它们.
处理 epub 封面页的方式与自动解析图像路径并将图像放入 _images 目录的 reStructuredText 过程不同.对于 epub 封面页,将图像放在 html_static_path 目录中,并在 epub_cover 配置选项中使用其完整路径引用它.
kindlegen 命令可以将 epub3 生成的文件转换为 .mobi 文件以供 Kindle 使用.执行以下命令后,您可以在 _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-链接

可以使用 texinfo_cross_references 禁用文档中的内联引用生成.这使得使用独立阅读器（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文件中的不同 节点 .
冒号 (:) 在菜单项和交叉引用中无法正确转义.它们将被替换为分号 (;).
可以使用某种官方的URI方案 info 创建指向外部信息文件的链接.例如:
```
info:Texinfo#makeinfo_options
```