Sphinx常见问题解答¶

这是关于Sphinx的常见问题列表。请随意推荐新条目！

我该怎么办 ...¶

... 没有 Latex 的情况下创建PDF文件？: rinohtype 提供一个PDF生成器，可作为 Latex 生成器的插入替换。
…获取分区号？: 它们在 Latex 输出中是自动的；对于HTML，给出 :numbered: 选择权 toctree 要开始编号的指令。
…自定义生成的HTML文件的外观？: 使用主题，请参阅 HTML主题化 .
…添加全局替换还是包含？: 将它们添加到 rst_prolog 或 rst_epilog 配置值。
…在侧边栏中显示整个目录树？: 使用 toctree 可在自定义布局模板中调用，可能在 sidebartoc 块。
…写我自己的分机？: 见扩展教程 .
…使用MoinMoin标记从现有文档转换？: 最简单的方法是转换为XHTML，然后转换 xhtml to reST . 您仍然需要标记类等，但是标题和代码示例是清晰的。

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

用Sphinx…¶

阅读文档

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

埃皮多克

第三方扩展提供 api role 对于给定的标识符，它引用epydoc的api文档。

编程辅助工具

Michael Jones正在开发一个到Doxygen的rest/sphinx桥，叫做 breathe .

SCons

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

皮皮

詹尼斯·莱德尔写了一篇 setuptools command 它会自动将sphinx文档上传到pypi包文档区域，网址为https://pythonhosted.org/。

GITHUB页面

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

MediaWiki

看见 sphinx-wiki ，凯文·邓恩的一个项目。

谷歌分析

您可以使用自定义 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 Search替换Sphinx的内置搜索功能，请执行以下操作：

转到https://cse.google.com/cse/all创建谷歌搜索代码段。

复制代码段并粘贴到 _templates/searchbox.html 在你的Sphinx项目中：

<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与多库提尔¶

tl；dr： docutils公司 将reStructuredText转换为多种输出格式。Sphinx建立在docutils之上，允许构建交叉引用和索引的文档体。

docutils __是一个文本处理系统，用于将纯文本文档转换为其他更丰富的格式。如中所述 `docutils documentation`_ _，docutils使用读者要阅读文档， 分析器 用于将纯文本格式解析为由不同类型的结点和作家以各种文档格式输出此树。docutils为一种纯文本格式提供解析器- `reStructuredText`_ _-尽管是其他的， out-of-tree 已经实现了解析器，包括Sphinx的 Markdown parser . 另一方面，它为许多不同的格式提供了编写器，包括HTML、LaTeX、手册页、开放文档格式和XML。

docutils通过 `front-end tools`_ _，例如 rst2html ， rst2odt 和 rst2xml . 不过，最重要的是，所有这些工具以及文档本身都与单个文档有关。它们不支持交叉引用、文档索引或文档层次结构的构建（通常在目录中显示）等概念。

Sphinx通过利用docutils的读者和解析器并提供自己的 Builders . 因此，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仅显示在第一页。在这种情况下，您可以复制 epub.css 从 sphinx/themes/epub/static/ 本地目录 _static/ 目录并删除浮动设置。
在外部插入的文件 toctree 必须手动包含指令。这有时适用于附录，例如术语表或索引。您可以将它们与 epub_post_files 选择权。
epub封面的处理与restructuredtext过程不同，后者自动解析图像路径并将图像放入 _images 目录。对于电子版封面，请将图像放入 html_static_path 目录并用它在 epub_cover 配置选项。

kindlegen 命令可以从EPUB3结果文件转换为 .mobi Kindle文件。你可以得到 yourdoc.mobi 在下面 _build/epub 在执行以下命令之后：

$ 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.

文本信息¶

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

显示链接¶

对于生成的信息文件，您可能会遇到一个明显的问题，即如何显示引用。如果您读取信息文件的源，对该节的引用如下所示：

* 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的文档的最佳方法，因为它们经常使用链接，并且不考虑此限制。但是，更改此变量会影响所有信息文档的显示方式，大多数情况下都会将此行为考虑在内。

如果要Emacs显示由Sphinx生成的信息文件，请使用该值 hide 对于 Info-hide-note-references 以及所有其他信息文件的默认值，尝试将以下EmacsLisp代码添加到启动文件中， ~/.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文件，以下注释可能会有所帮助：

每个部分对应不同的 node 在信息文件中。
科隆 (: ）无法在菜单项和外部参照中正确转义。它们将被分号替换 (; ）
可以使用稍微正式的URI方案创建到外部信息文件的链接 info . 例如：：
```
info:Texinfo#makeinfo_options
```

Sphinx

On this page

Site navigation