Sphinx Documentation

Sphinx Documentation

Release 1.5.6 Georg Brandl

May 14, 2017

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

2.4 Adding content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

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

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

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

2.8 Autodoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

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

2.10 More topics to be covered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

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

3.5 Project templating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

4 Invocation of sphinx-build

13

4.1 Environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.2 Makefile options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4.3 Deprecation Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Invocation of sphinx-apidoc

17

6 reStructuredText Primer

19

6.1 Paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6.2 Inline markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

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

6.4 Source Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

i

6.5 Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 6.6 Hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 6.7 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.8 Explicit Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.9 Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 6.10 Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 6.11 Footnotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 6.12 Citations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 6.13 Substitutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 6.14 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 6.15 Source encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 6.16 Gotchas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

7 Sphinx Markup Constructs

29

7.1 The TOC tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

7.2 Paragraph-level markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.3 Table-of-contents markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

7.4 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

7.5 Grammar production displays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

7.6 Showing code examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

7.7 Inline markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

7.8 Miscellaneous markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

8 Sphinx Domains

51

8.1 What is a Domain? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

8.2 Basic Markup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

8.3 The Python Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

8.4 The C Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

8.5 The C++ Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

8.6 The Standard Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

8.7 The JavaScript Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

8.8 The reStructuredText domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

8.9 More domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

9 Available builders

71

9.1 Serialization builder details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

10 The build configuration file

79

10.1 General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

10.2 Project information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

10.3 Options for internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

10.4 Options for HTML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

10.5 Options for Apple Help output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

10.6 Options for epub output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

10.7 Options for LaTeX output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

10.8 Options for text output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

10.9 Options for manual page output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

10.10 Options for Texinfo output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

10.11 Options for the linkcheck builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

10.12 Options for the XML builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

10.13 Options for the C++ domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

11 Example of configuration file

109

12 Internationalization

117

ii

12.1 Sphinx internationalization details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 12.2 Translating with sphinx-intl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 12.3 Using Transifex service for team translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 12.4 Contributing to Sphinx reference translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

13 HTML theming support

123

13.1 Using a theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

13.2 Builtin themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

13.3 Creating themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

13.4 Third Party Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

14 Templating

131

14.1 Do I need to use Sphinx's templates to produce HTML? . . . . . . . . . . . . . . . . . . . . . 131

14.2 Jinja/Sphinx Templating Primer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

14.3 Working with the builtin templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

15 LaTeX customization

137

15.1 Basic customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

15.2 The Sphinx LaTeX style package options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

15.3 The LaTeX environments defined by Sphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

16 Markdown support

145

16.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

17 Sphinx Extensions

147

17.1 Builtin Sphinx extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

17.2 Third-party extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

18 Developing extensions for Sphinx

183

18.1 Extension metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

18.2 APIs used for writing extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

19 Sphinx Web Support

211

19.1 Web Support Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

19.2 The WebSupport Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

19.3 Search Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

19.4 Storage Backends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

20 Sphinx FAQ

223

20.1 How do I... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

20.2 Using Sphinx with... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

20.3 Epub info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

20.4 Texinfo info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

21 Glossary

229

22 Sphinx Developer's Guide

231

22.1 Bug Reports and Feature Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

22.2 Contributing to Sphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

22.3 Coding Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

22.4 Deprecating a feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

22.5 Deprecation policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

23 Changes in Sphinx

237

23.1 Release 1.5.6 (released May 15, 2017) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

23.2 Release 1.5.5 (released Apr 03, 2017) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

iii

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

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

Google Online Preview   Download