Sphinx Documentation

Sphinx Documentation

Release 1.4.9 Georg Brandl

Nov 23, 2016

Contents

1 Introduction

1

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

1.2 Use with other systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

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

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

2 First Steps with Sphinx

3

2.1 Install Sphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.2 Setting up the documentation sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.3 Defining document structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2.4 Adding content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.5 Running the build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.6 Documenting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.7 Basic configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.8 Autodoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.9 Intersphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.10 More topics to be covered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Invocation of sphinx-quickstart

9

3.1 Structure options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.2 Project basic options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3.3 Extension options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3.4 Makefile and Batchfile creation options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4 Invocation of sphinx-build

11

4.1 Makefile options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5 Invocation of sphinx-apidoc

15

6 reStructuredText Primer

17

6.1 Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.2 Inline markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

6.3 Lists and Quote-like blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

6.4 Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.5 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.6 Hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

6.7 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6.8 Explicit Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

6.9 Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

i

6.10 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.11 Footnotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 6.12 Citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 6.13 Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 6.14 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 6.15 Source encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 6.16 Gotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

7 Sphinx Markup Constructs

27

7.1 The TOC tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

7.2 Paragraph-level markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

7.3 Table-of-contents markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.4 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.5 Grammar production displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

7.6 Showing code examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

7.7 Inline markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

7.8 Miscellaneous markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

8 Sphinx Domains

47

8.1 What is a Domain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8.2 Basic Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

8.3 The Python Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

8.4 The C Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

8.5 The C++ Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

8.6 The Standard Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

8.7 The JavaScript Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

8.8 The reStructuredText domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

8.9 More domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

9 Available builders

65

9.1 Serialization builder details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

10 The build configuration file

73

10.1 General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

10.2 Project information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

10.3 Options for internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

10.4 Options for HTML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

10.5 Options for Apple Help output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

10.6 Options for epub output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

10.7 Options for LaTeX output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

10.8 Options for text output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

10.9 Options for manual page output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

10.10 Options for Texinfo output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

10.11 Options for the linkcheck builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

10.12 Options for the XML builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

11 Internationalization

101

11.1 Sphinx internationalization details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

11.2 Translating with sphinx-intl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

11.3 Using Transifex service for team translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

11.4 Contributing to Sphinx reference translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

12 HTML theming support

107

12.1 Using a theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

12.2 Builtin themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

ii

12.3 Creating themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 12.4 Third Party Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

13 Templating

115

13.1 Do I need to use Sphinx's templates to produce HTML? . . . . . . . . . . . . . . . . . . . . . 115

13.2 Jinja/Sphinx Templating Primer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

13.3 Working with the builtin templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

14 Sphinx Extensions

121

14.1 Builtin Sphinx extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

14.2 Third-party extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

15 Developing extensions for Sphinx

155

15.1 Extension metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

15.2 APIs used for writing extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

16 Sphinx Web Support

181

16.1 Web Support Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

16.2 The WebSupport Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

16.3 Search Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

16.4 Storage Backends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

17 Sphinx FAQ

193

17.1 How do I... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

17.2 Using Sphinx with... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

17.3 Epub info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

17.4 Texinfo info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

18 Glossary

197

19 Sphinx Developer's Guide

199

19.1 Bug Reports and Feature Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

19.2 Contributing to Sphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

19.3 Coding Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

20 Changes in Sphinx

205

20.1 Release 1.4.9 (released Nov 23, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

20.2 Release 1.4.8 (released Oct 1, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

20.3 Release 1.4.7 (released Oct 1, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

20.4 Release 1.4.6 (released Aug 20, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

20.5 Release 1.4.5 (released Jul 13, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

20.6 Release 1.4.4 (released Jun 12, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

20.7 Release 1.4.3 (released Jun 5, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

20.8 Release 1.4.2 (released May 29, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

20.9 Release 1.4.1 (released Apr 12, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

20.10 Release 1.4 (released Mar 28, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

20.11 Release 1.3.6 (released Feb 29, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

20.12 Release 1.3.5 (released Jan 24, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

20.13 Release 1.3.4 (released Jan 12, 2016) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

20.14 Release 1.3.3 (released Dec 2, 2015) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

20.15 Release 1.3.2 (released Nov 29, 2015) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

20.16 Release 1.3.1 (released Mar 17, 2015) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

20.17 Release 1.3 (released Mar 10, 2015) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

20.18 Release 1.3b3 (released Feb 24, 2015) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

20.19 Release 1.3b2 (released Dec 5, 2014) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

iii

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

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

Google Online Preview   Download