Sphinx 常问问题

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

我如何能…

… 创建没有LaTeX的PDF文件？

rinohtype provides PDF构建器，可用作LaTeX构建器的替代品。

… 获得部分号码？

They are automatic in LaTeX output; for HTML, give a :numbered: option to the toctree directive where you want to start numbering.

… 自定义构建的HTML文件的外观？

使用主题，请参阅 HTML.

… 添加全球替换或包括？

Add them in the rst_prolog or rst_epilog config value.

… 在侧边栏中显示整个TOC树？

Use the toctree callable in a custom layout template, probably in the sidebartoc block.

… 写我自己的扩展？

See the 扩展教程.

… 使用MoinMoin标记从我现有的文档转换？

The easiest way is to convert to xhtml, then convert xhtml to reST. You’ll still need to mark up classes and such, but the headings and code examples come through cleanly.

… 从Sphinx文档创建HTML幻灯片？

See the “Hieroglyph” package at https://github.com/nyergler/hieroglyph.

For many more extensions and other contributed stuff, see the sphinx-contrib repository.

使用Sphinx…

Read the Docs

https://readthedocs.org is a documentation hosting service based around Sphinx. They will host sphinx documentation, along with supporting a number of other features including version support, PDF generation, and more. The Getting Started guide is a good place to start.

Epydoc

There’s a third-party extension providing an api role which refers to Epydoc’s API docs for a given identifier.

Doxygen

Michael Jones is developing a reST/Sphinx bridge to doxygen called breathe.

SCons

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

PyPI

Jannis Leidel wrote a setuptools command that automatically uploads Sphinx documentation to the PyPI package documentation area at https://pythonhosted.org/.

GitHub Pages

Directories starting with underscores are ignored by default which breaks static files in Sphinx. GitHub’s preprocessor can be disabled to support Sphinx HTML output properly.

MediaWiki

See https://bitbucket.org/kevindunn/sphinx-wiki/wiki/Home, a project by Kevin Dunn.

Google Analytics

You can use a custom layout.html template, like this:

{% extends "!layout.html" %}

{%- block extrahead %}
{{ super() }}
<script type="text/javascript">
  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 type="text/javascript">
  (function() {
    var ga = document.createElement('script');
    ga.src = ('https:' == document.location.protocol ?
              'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    ga.setAttribute('async', 'true');
    document.documentElement.firstChild.appendChild(ga);
  })();
</script>
</div>
{% endblock %}
Google Search

To replace Sphinx’s built-in search function with Google Search, proceed as follows:

  1. Go to https://cse.google.com/cse/all to create the Google Search code snippet.

  2. Copy the code snippet and paste it into _templates/searchbox.html in your Sphinx project:

    <div>
   <h3>{{ _('Quick search') }}</h3>
   <script>
      (function() {
         var cx = '......';
         var gcse = document.createElement('script');
         gcse.type = 'text/javascript';
         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. Add searchbox.html to the html_sidebars configuration value.

Epub 信息

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

  • 将文本拆分为多个文件。单个HTML文件越长，电子书阅读器渲染它们的时间就越长。在极端情况下，渲染可能需要一分钟。

  • 尽量减少标记。这也支付渲染时间。

  • For some readers you can use embedded or external fonts using the CSS @font-face directive. This is extremely useful for code listings which are often cut at the right margin. The default Courier font (or variant) is quite wide and you can only display up to 60 characters on a line. If you replace it with a narrower font, you can get more characters on a line. You may even use FontForge and create narrow variants of some free font. In my case I get up to 70 characters on a line.

    您可能需要进行一些实验，直到获得合理的结果。

  • Test the created epubs. You can use several alternatives. The ones I am aware of are Epubcheck, Calibre, FBreader (although it does not render the CSS), and Bookworm. For Bookworm, you can download the source from https://code.google.com/archive/p/threepress and run your own local server.

  • Large floating divs are not displayed properly. If they cover more than one page, the div is only shown on the first page. In that case you can copy the epub.css from the sphinx/themes/epub/static/ directory to your local _static/ directory and remove the float settings.

  • Files that are inserted outside of the toctree directive must be manually included. This sometimes applies to appendixes, e.g. the glossary or the indices. You can add them with the epub_post_files option.

  • The handling of the epub cover page differs from the reStructuredText procedure which automatically resolves image paths and puts the images into the _images directory. For the epub cover page put the image in the html_static_path directory and reference it with its full path in the epub_cover config option.

  • kindlegen command can convert from epub3 resulting file to .mobi file for Kindle. You can get yourdoc.mobi under _build/epub after the following command:

    $ make epub
$ kindlegen _build/epub/yourdoc.epub

    The kindlegen command doesn’t accept documents that have section titles surrounding toctree directive:

    Section Title
=============

.. toctree::

   subdocument

Section After Toc Tree
======================

    kindlegen assumes all documents order in line, but the resulting document has complicated order for kindlegen:

    ``parent.xhtml`` -> ``child.xhtml`` -> ``parent.xhtml``

    If you get the following error, fix your document structure:

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

注释

The following notes may be helpful if you want to create Texinfo files:

  • Each section corresponds to a different node in the Info file.

  • Colons (:) cannot be properly escaped in menu entries and xrefs. They will be replaced with semicolons (;).

  • Links to external Info files can be created using the somewhat official URI scheme info. For example:

    info:Texinfo#makeinfo_options

  • Inline markup

    The standard formatting for *strong* and _emphasis_ can result in ambiguous output when used to markup parameter names and other values. Since this is a fairly common practice, the default formatting has been changed so that emphasis and strong are now displayed like `literal's.

    The standard formatting can be re-enabled by adding the following to your conf.py:

    texinfo_elements = {'preamble': """
@definfoenclose strong,*,*
@definfoenclose emph,_,_
"""}