Sphinx Documentation Release 1.6.7 Georg Brandl Feb 04, 2018 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-quickstart9 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......................................... 46 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........................................ 68 8.8 The reStructuredText domain..................................... 69 8.9 More domains............................................. 70 9 Available builders 71 9.1 Serialization builder details...................................... 77 10 The build configuration file 79 10.1 General configuration......................................... 80 10.2 Project information........................................... 85 10.3 Options for internationalization................................... 86 10.4 Options for HTML output....................................... 89 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........................................ 106 10.9 Options for manual page output................................... 106 10.10 Options for Texinfo output...................................... 107 10.11 Options for the linkcheck builder.................................. 108 10.12 Options for the XML builder..................................... 109 10.13 Options for the C++ domain..................................... 109 11 Example of configuration file 111 12 Internationalization 119 ii 12.1 Sphinx internationalization details.................................. 120 12.2 Translating with sphinx-intl...................................... 121 12.3 Using Transifex service for team translation............................ 122 12.4 Contributing to Sphinx reference translation............................ 124 13 HTML theming support 125 13.1 Using a theme.............................................. 125 13.2 Builtin themes............................................. 126 13.3 Creating themes............................................ 130 13.4 Distribute your theme as a python package............................. 131 13.5 Third Party Themes.......................................... 132 14 Setuptools integration 133 14.1 Using setuptools integration..................................... 133 14.2 Options for setuptools integration.................................. 134 15 Templating 137 15.1 Do I need to use Sphinx’s templates to produce HTML?..................... 137 15.2 Jinja/Sphinx Templating Primer................................... 137 15.3 Working with the builtin templates................................. 138 16 LaTeX customization 143 16.1 Basic customization.......................................... 143 16.2 The LaTeX style file options...................................... 144 16.3 LaTeX macros and environments................................... 147 17 Markdown support 151 17.1 Configuration.............................................. 151 18 Sphinx Extensions 153 18.1 Builtin Sphinx extensions....................................... 153 18.2 Third-party extensions......................................... 188 19 Developing extensions for Sphinx 189 19.1 Discovery of builders by entry point................................. 189 19.2 Extension metadata.......................................... 190 19.3 APIs used for writing extensions................................... 190 20 Sphinx Web Support 219 20.1 Web Support Quick Start....................................... 219 20.2 The WebSupport Class......................................... 223 20.3 Search Adapters............................................ 226 20.4 Storage Backends............................................ 228 21 Sphinx FAQ 231 21.1 How do I. ................................................ 231 21.2 Using Sphinx with. .......................................... 232 21.3 Epub info................................................ 233 21.4 Texinfo info............................................... 234 22 Glossary 237 23 Sphinx Developer’s Guide 239 23.1 Bug Reports and Feature Requests.................................. 240 23.2 Contributing to Sphinx........................................ 240 23.3 Coding Guide.............................................. 243 iii 23.4 Deprecating a feature......................................... 244 23.5 Deprecation policy........................................... 244 23.6 Unit Testing............................................... 244 24 Changes in Sphinx 247 24.1 Release 1.6.7 (released Feb 04, 2018)................................. 247 24.2 Release 1.6.6 (released Jan 08, 2018)................................. 248 24.3 Release 1.6.5 (released Oct 23, 2017)................................. 248 24.4 Release 1.6.4 (released Sep 26, 2017)................................. 249 24.5 Release 1.6.3 (released Jul 02, 2017).................................. 250 24.6 Release 1.6.2 (released May 28, 2017)................................. 251 24.7 Release 1.6.1 (released May 16, 2017)................................. 252 24.8 Release 1.6 (unreleased)........................................ 257 24.9 Release 1.5.6 (released May 15, 2017)................................. 257 24.10 Release 1.5.5 (released Apr 03, 2017)................................. 257 24.11 Release 1.5.4 (released Apr 02, 2017)................................. 258 24.12 Release 1.5.3 (released Feb 26, 2017)................................. 258 24.13 Release 1.5.2 (released Jan 22, 2017)................................. 259 24.14 Release 1.5.1 (released Dec 13, 2016)................................. 260 24.15 Release 1.5 (released Dec 5, 2016)................................... 261 24.16 Release 1.4.9 (released Nov 23, 2016)................................. 267 24.17 Release 1.4.8 (released Oct 1, 2016).................................. 267 24.18 Release 1.4.7 (released Oct 1, 2016).................................