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

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

6.7 The JavaScript Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

6.8 The reStructuredText domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

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 (Jul 23, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

14.2 Release 0.6.8 (in development) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

14.3 Release 0.6.7 (Jun 05, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

14.4 Release 0.6.6 (May 25, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

14.5 Release 0.6.5 (Mar 01, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

14.6 Release 0.6.4 (Jan 12, 2010) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

14.7 Release 0.6.3 (Sep 03, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

14.8 Release 0.6.2 (Jun 16, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

14.9 Release 0.6.1 (Mar 26, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

14.10 Release 0.6 (Mar 24, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

14.11 Release 0.5.2 (Mar 24, 2009) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

14.12 Release 0.5.1 (Dec 15, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

14.13 Release 0.5 (Nov 23, 2008) ? Birthday release! . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

14.14 Release 0.4.3 (Oct 8, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

14.15 Release 0.4.2 (Jul 29, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

14.16 Release 0.4.1 (Jul 5, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

14.17 Release 0.4 (Jun 23, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

14.18 Release 0.3 (May 6, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

14.19 Release 0.2 (Apr 27, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

14.20 Release 0.1.61950 (Mar 26, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

14.21 Release 0.1.61945 (Mar 26, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

14.22 Release 0.1.61843 (Mar 24, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

14.23 Release 0.1.61798 (Mar 23, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

14.24 Release 0.1.61611 (Mar 21, 2008) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

15 Projects using Sphinx

145

15.1 Documentation using the default theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

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

15.3 Documentation using the sphinxdoc theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

15.4 Documentation using another builtin theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

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

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

Python Module Index

149

iii

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

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

Google Online Preview   Download