LGRpplxcmr LGRphvcmss LGRpcrcmtt X2pplxcmr …
LGRpplxcmr LGRphvcmss LGRpcrcmtt X2pplxcmr X2phvcmss X2pcrcmtt
Sphinx Documentation
1.8.5 Georg Brandl
2019 03 29
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 Installing Sphinx
3
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 macOS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.5 Installation from PyPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.6 Installation from source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 Getting Started
7
3.1 Setting up the documentation sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.2 Defining document structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.3 Adding content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.4 Running the build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.5 Documenting objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3.6 Basic configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.7 Autodoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.8 Intersphinx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.9 More topics to be covered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4 reStructuredText
13
4.1 reStructuredText Primer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.2 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.3 Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
4.4 Field Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.5 Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5 Markdown
69
5.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
6 Configuration
71
6.1 Project information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
i
6.2 General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 6.3 Options for internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 6.4 Options for Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 6.5 Options for HTML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 6.6 Options for Single HTML output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 6.7 Options for HTML help output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 6.8 Options for Apple Help output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 6.9 Options for epub output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 6.10 Options for LaTeX output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 6.11 Options for text output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 6.12 Options for manual page output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 6.13 Options for Texinfo output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 6.14 Options for QtHelp output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 6.15 Options for the linkcheck builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 6.16 Options for the XML builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 6.17 Options for the C++ domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
7 Builders
109
7.1 Serialization builder details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
8 Extensions
117
8.1 Built-in extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
8.2 Third-party extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
9 HTML
159
9.1 Builders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
9.2 Themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
10 Internationalization
167
10.1 Sphinx internationalization details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
10.2 Translating with sphinx-intl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
10.3 Using Transifex service for team translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
10.4 Contributing to Sphinx reference translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
11 Setuptools integration
173
11.1 Using setuptools integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
11.2 Options for setuptools integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
12 Sphinx Web Support
177
12.1 Web Support Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
12.2 The WebSupport Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
12.3 Search Adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
12.4 Storage Backends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
13 Man Pages
189
13.1 Core Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
13.2 Additional Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
14 HTML theming support
199
14.1 Creating themes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
14.2 Distribute your theme as a Python package . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
14.3 Templating . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
15 Templating
203
15.1 Do I need to use Sphinx's templates to produce HTML? . . . . . . . . . . . . . . . . . . . . . 203
ii
15.2 Jinja/Sphinx Templating Primer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 15.3 Working with the builtin templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
16 LaTeX customization
209
16.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
16.2 The latex_elements configuration setting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
16.3 'sphinxsetup' key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
16.4 LaTeX macros and environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
17 Developing extensions for Sphinx
221
17.1 Discovery of builders by entry point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
17.2 Important objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
17.3 Build Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
17.4 Extension metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
17.5 APIs used for writing extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
18 Extension tutorials
261
18.1 Developing a "Hello world" extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
18.2 Developing a "TODO" extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
18.3 Developing a "recipe" extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
19 Sphinx FAQ
283
19.1 How do I. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
19.2 Using Sphinx with. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
19.3 Epub info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
19.4 Texinfo info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
20 Glossary
289
21 Changes in Sphinx
291
22 Sphinx authors
293
Python
295
297
iii
iv
1 CHAPTER
Introduction
This is the documentation for the Sphinx documentation builder. Sphinx is a tool that translates a set of reStructuredText3 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 PDF file using LaTeX. The focus is on hand-written documentation, rather than auto-generated API docs. Though there is support for that kind of documentation as well (which is intended to be freely mixed with hand-written content), if you need pure API docs have a look at Epydoc4, which also understands reST. For a great "introduction" to writing docs in general ? the whys and hows, see also Write the docs5, written by Eric Holscher.
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 the Python Package Index6.
? For converting the old Python docs to Sphinx, a converter was written which can be found at the Python SVN repository7. 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 GitHub8.
3 4 5 6 7 8
1
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.