Sphinx常见问题解答¶

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

我该如何…¶

不用LaTeX创建pdf文件？: `rinohtype`а提供了一个PDF构建器，可以作为LaTeX构建器的直接替代品。
获取到节的数目？: 它们在LaTeX输出中是自动的；对于HTML，为：rst:方向：`toctree`指令，从中开始编号。
… 自定义生成的HTML文件的外观？: 使用主题，请参阅：doc:/usage/theming。
… 添加全局替换或包含？: 将它们添加到：confval:`rst_prolog`或：confval:`rst_epilog`配置值中。
… 在侧边栏中显示整个目录树？: 在自定义布局模板中使用可调用的：data:`toctree’，可能在`sidebartoc``块中。
… 编写我自己的插件?: 请参阅：doc:/development/tutorials/index。
… 使用MoinMoin标记从现有文档转换？: 最简单的方法是转换为xhtml，然后将“xhtml转换为reST”。您仍然需要标记类之类的，但是标题和代码示例清晰明了。

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

用…使用sphinx¶

阅读文档

`阅读文档<https://readthedocs.org>`_是一个基于Sphinx的文档托管服务。他们将托管sphinx文档，同时支持许多其他功能，包括版本支持、PDF生成等。《入门指南》是一个很好的起点。

Epy文档

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

编程辅助工具

迈克尔琼斯正在开发一个reST/Sphinx桥到编程辅助工具，名为“breathe”<https://github.com/michaeljones/breathe/tree/master>`_.

SCons

Glenn Hutchings has written a SCons build script to build Sphinx documentation; it is hosted here: https://bitbucket-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html

PyPI

Jannis Leidel编写了一个`setuptools命令<https://pypi.org/project/Sphinx-pypi-upload/>`_它会自动将Sphinx文档上载到位于的PyPI包文档区域https://pythonhosted.org/。

GitHub页面

请添加：py:mod:`HubGitSphinx`你的项目。它允许您在GitHub页面中发布文档。它在自动生成HTML文档时为GitHub页面生成帮助文件。

维基百科

See sphinx-wiki, a project by 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搜索代码片段。

复制代码段并将其粘贴到模板中/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``到：confval:`html_sidebars`配置值。

Sphinx 和 Docutils¶

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

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

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

Sphinx通过利用docutils的读取器和解析器并提供自己的：doc:/usage/builders/index，在docutils的基础上构建。因此，Sphinx包装了docutils提供的一些*writers*。这使得Sphinx能够提供许多docutils无法提供的特性，比如上面概述的那些特性。

Epub信息¶

下表给出了创建epub文件的一些提示：

把文本分成几个文件。单个HTML文件越长，电子书阅读器呈现它们的时间就越长。在极端情况下，渲染可能需要一分钟。
尽量减少标记。这也会增加渲染时间。
对于某些读者，可以使用CSS`@font face``指令使用嵌入式或外部字体。这对于经常在右边空白处剪切的代码列表非常有用。默认的Courier字体（或变体）非常宽，一行最多只能显示60个字符。如果用更窄的字体替换它，可以在一行中获得更多字符。你甚至可以用FontForge<https://fontforge.github.io/>`_并创建一些自由字体的窄变体。在我的例子中，一行最多有70个字符。

在得到合理的结果之前，你可能要做一些实验。
测试创建的ePub。你可以使用几种选择。我知道的是Epubcheck、Calibre、fbreder（尽管它不呈现CSS）和bookmoom。对于Bookworm，您可以从https://code.google.com/archive/p/threepress运行自己的本地服务器。
大的浮动div未正确显示。如果它们覆盖多个页面，则div只显示在第一页上。在这种情况下，您可以复制：文件：`电子邮箱.css`从“sphinx/themes/epub/static/``目录到本地的`u static/``目录，并删除float设置。
必须手动包含在“toctree”指令之外插入的文件。这有时适用于附录，例如术语表或索引。您可以使用：confval:`epub_post_files`选项添加它们。
epub封面页的处理不同于recostructedText过程，后者自动解析图像路径并将图像放入“u images”目录。对于epub封面页，请将图像放在：confval:html_static_path`目录中，并在：confval:`epub_cover config选项中引用它的完整路径。
kindlegen_u命令可以将epub3生成的文件转换为Kindle的`.mobi``文件。你可以得到``你的医生.mobi``在以下命令后的“u 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.
```

Texinfo信息¶

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

展示链接¶

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

* note Displaying Links: target-id

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

展示链接

One can disable generation of the inline references in a document with texinfo_cross_references. That makes an info file more readable with stand-alone reader (info).

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

如果希望Emacs显示Sphinx生成的信息文件，并使用“Info hide note references”的“hide”值和所有其他信息文件的默认值，请尝试将以下Emacs Lisp代码添加到启动文件“~/.Emacs.d”中/初始标高``.

(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:Texinfo#makeinfo_options
```

Sphinx

On this page

Site navigation