Sphinx Documentation - Read the Docs

Sphinx Documentation

Release 1.3.1 Georg Brandl

September 22, 2015

Contents

1 Introduction

1

1.1 Conversion from other systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2 Use with other systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.4 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

2 First Steps with Sphinx

3

2.1 Setting up the documentation sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.2 Defining document structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.3 Adding content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.4 Running the build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.5 Documenting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.6 Basic configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.7 Autodoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.8 More topics to be covered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Invocation of sphinx-build

9

3.1 Makefile options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 reStructuredText Primer

13

4.1 Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.2 Inline markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4.3 Lists and Quote-like blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4.4 Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.5 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.6 Hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.7 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4.8 Explicit Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.9 Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.10 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4.11 Footnotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.12 Citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.13 Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.14 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.15 Source encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.16 Gotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

5 Sphinx Markup Constructs

21

i

5.1 The TOC tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.2 Paragraph-level markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 5.3 Table-of-contents markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.4 Index-generating markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.5 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 5.6 Grammar production displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.7 Showing code examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 5.8 Inline markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 5.9 Miscellaneous markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

6 Sphinx Domains

37

6.1 What is a Domain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.2 Basic Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

6.3 The Python Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

6.4 The C Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

6.5 The C++ Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

6.6 The Standard Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

6.7 The JavaScript Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

6.8 The reStructuredText domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

6.9 More domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

7 Available builders

49

7.1 Serialization builder details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

8 The build configuration file

55

8.1 General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

8.2 Project information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

8.3 Options for HTML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

8.4 Options for epub output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

8.5 Options for LaTeX output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

8.6 Options for manual page output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

9 HTML theming support

69

9.1 Using a theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

9.2 Builtin themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

9.3 Creating themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

10 Templating

77

10.1 Do I need to use Sphinx' templates to produce HTML? . . . . . . . . . . . . . . . . . . . . . . 77

10.2 Jinja/Sphinx Templating Primer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

10.3 Working with the builtin templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

11 Sphinx Extensions

83

11.1 Tutorial: Writing a simple extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

11.2 Extension API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

11.3 Writing new builders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

11.4 Builtin Sphinx extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

11.5 Third-party extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

12 Sphinx FAQ

119

12.1 How do I... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

12.2 Using Sphinx with... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

12.3 Epub info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

13 Glossary

123

ii

14 Changes in Sphinx

125

14.1 Release 1.0.8 (Sep 23, 2011) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

14.2 Release 1.0.7 (Jan 15, 2011) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

14.3 Release 1.0.6 (Jan 04, 2011) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

14.4 Release 1.0.5 (Nov 12, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

14.5 Release 1.0.4 (Sep 17, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

14.6 Release 1.0.3 (Aug 23, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

14.7 Release 1.0.2 (Aug 14, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

14.8 Release 1.0.1 (Jul 27, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

14.9 Release 1.0 (Jul 23, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

14.10 Release 0.6.7 (Jun 05, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

14.11 Release 0.6.6 (May 25, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

14.12 Release 0.6.5 (Mar 01, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

14.13 Release 0.6.4 (Jan 12, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

14.14 Release 0.6.3 (Sep 03, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

14.15 Release 0.6.2 (Jun 16, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

14.16 Release 0.6.1 (Mar 26, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

14.17 Release 0.6 (Mar 24, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

14.18 Release 0.5.2 (Mar 24, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

14.19 Release 0.5.1 (Dec 15, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

14.20 Release 0.5 (Nov 23, 2008) ? Birthday release! . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

14.21 Release 0.4.3 (Oct 8, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

14.22 Release 0.4.2 (Jul 29, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

14.23 Release 0.4.1 (Jul 5, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

14.24 Release 0.4 (Jun 23, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

14.25 Release 0.3 (May 6, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

14.26 Release 0.2 (Apr 27, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

14.27 Release 0.1.61950 (Mar 26, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

14.28 Release 0.1.61945 (Mar 26, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

14.29 Release 0.1.61843 (Mar 24, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

14.30 Release 0.1.61798 (Mar 23, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

14.31 Release 0.1.61611 (Mar 21, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

15 Projects using Sphinx

149

15.1 Documentation using the default theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

15.2 Documentation using a customized version of the default theme . . . . . . . . . . . . . . . . 150

15.3 Documentation using the sphinxdoc theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

15.4 Documentation using another builtin theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

15.5 Documentation using a custom theme/integrated in a site . . . . . . . . . . . . . . . . . . . . 152

15.6 Homepages and other non-documentation sites . . . . . . . . . . . . . . . . . . . . . . . . . . 153

15.7 Books produced using Sphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Python Module Index

155

iii

iv

CHAPTER 1

Introduction

This is the documentation for the Sphinx documentation builder. Sphinx is a tool that translates a set of reStructuredText source files into various output formats, automatically producing cross-references, indices etc. That is, if you have a directory containing a bunch of reST-formatted documents (and possibly subdirectories of docs in there as well), Sphinx can generate a nicely-organized arrangement of HTML files (in some other directory) for easy browsing and navigation. But from the same source, it can also generate a LaTeX file that you can compile into a PDF version of the documents, or a PDF file directly using rst2pdf. The focus is on hand-written documentation, rather than auto-generated API docs. Though there is support for that kind of docs as well (which is intended to be freely mixed with hand-written content), if you need pure API docs have a look at Epydoc, which also understands reST.

1.1 Conversion from other systems

This section is intended to collect helpful hints for those wanting to migrate to reStructuredText/Sphinx from other documentation systems.

? Gerard Flanagan has written a script to convert pure HTML to reST; it can be found at BitBucket. ? For converting the old Python docs to Sphinx, a converter was written which can be found at the

Python SVN repository. It contains generic code to convert Python-doc-style LaTeX markup to Sphinx reST. ? Marcin Wojdyr has written a script to convert Docbook to reST with Sphinx markup; it is at Google Code. ? Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents to Sphinx: odt2sphinx. ? To convert different markups, Pandoc is a very helpful tool.

1.2 Use with other systems

See the pertinent section in the FAQ list.

1

Sphinx Documentation, Release 1.3.1

1.3 Prerequisites

Sphinx needs at least Python 2.4 to run, as well as the docutils and Jinja2 libraries. Sphinx should work with docutils version 0.5 or some (not broken) SVN trunk snapshot. If you like to have source code highlighting support, you must also install the Pygments library.

1.4 Usage

See First Steps with Sphinx for an introduction. It also contains links to more advanced sections in this manual for the topics it discusses.

2

Chapter 1. Introduction

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download