Sphinx FAQ — Sphinx documentation (original) (raw)

This is a list of Frequently Asked Questions about Sphinx. Feel free to suggest new entries!

How do I…

… create PDF files without LaTeX?

rinohtype provides a PDF builder that can be used as a drop-in replacement for the LaTeX builder.

… get section numbers?

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

… customize the look of the built HTML files?

Use themes, see HTML theming.

… add global substitutions or includes?

Add them in the rst_prolog or rst_epilog config value.

… display the whole TOC tree in the sidebar?

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

… write my own extension?

See the Tutorials.

… convert from my existing docs using MoinMoin markup?

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

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

Using Sphinx with…

Read the Docs

Read the Docs 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 has developed a reStructuredText/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-archive.softwareheritage.org/projects/zo/zondo/sphinx-scons.html

PyPI

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

GitHub Pages

Please add sphinx.ext.githubpages to your project. It allows you to publish your document in GitHub Pages. It generates helper files for GitHub Pages on building HTML document automatically.

MediaWiki

See sphinx-wiki, a project by Kevin Dunn.

Google Analytics

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

{% extends "!layout.html" %}

{%- block extrahead %} {{ super() }}

{% endblock %}

{% block footer %} {{ super() }}

This page uses Google Analytics to collect statistics. You can disable it by blocking the JavaScript coming from www.google-analytics.com.
{% 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:

    {{ _('Quick search') }}

  3. Add searchbox.html to the html_sidebars configuration value.

Sphinx vs. Docutils

tl;dr: docutils converts reStructuredText to multiple output formats. Sphinx builds upon docutils to allow construction of cross-referenced and indexed bodies of documentation.

docutils is a text processing system for converting plain text documentation into other, richer formats. As noted in the docutils documentation, docutils uses readers to read a document, parsers for parsing plain text formats into an internal tree representation made up of different types of nodes, and writers to output this tree in various document formats. docutils provides parsers for one plain text format -reStructuredText - though other, out-of-tree parsers have been implemented including Sphinx’s Markdown parser. On the other hand, it provides writers for many different formats including HTML, LaTeX, man pages, Open Document Format and XML.

docutils exposes all of its functionality through a variety of front-end tools, such as rst2html, rst2odt and rst2xml. Crucially though, all of these tools, and docutils itself, are concerned with individual documents. They don’t support concepts such as cross-referencing, indexing of documents, or the construction of a document hierarchy (typically manifesting in a table of contents).

Sphinx builds upon docutils by harnessing docutils’ readers and parsers and providing its own Builders. As a result, Sphinx wraps some of the writers provided by docutils. This allows Sphinx to provide many features that would simply not be possible with docutils, such as those outlined above.

Epub info

The following list gives some hints for the creation of epub files:

Texinfo info

There are two main programs for reading Info files, info and GNU Emacs. Theinfo program has less features but is available in most Unix environments and can be quickly accessed from the terminal. Emacs provides better font and color display and supports extensive customization (of course).

Displaying Links

One noticeable problem you may encounter with the generated Info files is how references are displayed. If you read the source of an Info file, a reference to this section would look like:

In the stand-alone reader, info, references are displayed just as they appear in the source. Emacs, on the other-hand, will by default replace*note: with see and hide the target-id. For example:

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

The exact behavior of how Emacs displays references is dependent on the variableInfo-hide-note-references. If set to the value of hide, Emacs will hide both the *note: part and the target-id. This is generally the best way to view Sphinx-based documents since they often make frequent use of links and do not take this limitation into account. However, changing this variable affects how all Info documents are displayed and most do take this behavior into account.

If you want Emacs to display Info files produced by Sphinx using the valuehide for Info-hide-note-references and the default value for all other Info files, try adding the following Emacs Lisp code to your start-up file,~/.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)))))

Notes

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