Sphinx Documentation Release 1.5.6 Georg Brandl Nov 13, 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 Man Pages 9 3.1 Core Applications...........................................9 3.2 Additional Applications........................................ 15 4 reStructuredText Primer 19 4.1 Paragraphs............................................... 19 4.2 Inline markup.............................................. 19 4.3 Lists and Quote-like blocks...................................... 20 4.4 Source Code............................................... 21 4.5 Tables.................................................. 22 4.6 Hyperlinks............................................... 22 4.7 Sections................................................. 23 4.8 Explicit Markup............................................ 23 4.9 Directives................................................ 23 4.10 Images.................................................. 25 4.11 Footnotes................................................ 26 4.12 Citations................................................. 26 4.13 Substitutions.............................................. 27 4.14 Comments................................................ 27 i 4.15 Source encoding............................................ 27 4.16 Gotchas................................................. 27 5 Sphinx Markup Constructs 29 5.1 The TOC tree.............................................. 29 5.2 Paragraph-level markup........................................ 32 5.3 Table-of-contents markup....................................... 34 5.4 Glossary................................................. 34 5.5 Grammar production displays.................................... 35 5.6 Showing code examples........................................ 36 5.7 Inline markup.............................................. 40 5.8 Miscellaneous markup......................................... 46 6 Sphinx Domains 51 6.1 What is a Domain?........................................... 51 6.2 Basic Markup.............................................. 51 6.3 The Python Domain.......................................... 53 6.4 The C Domain............................................. 58 6.5 The C++ Domain............................................ 59 6.6 The Standard Domain......................................... 67 6.7 The JavaScript Domain........................................ 68 6.8 The reStructuredText domain..................................... 70 6.9 More domains............................................. 71 7 Available builders 73 7.1 Serialization builder details...................................... 79 8 The build configuration file 81 8.1 General configuration......................................... 82 8.2 Project information........................................... 86 8.3 Options for internationalization................................... 87 8.4 Options for HTML output....................................... 90 8.5 Options for Apple Help output.................................... 96 8.6 Options for epub output........................................ 98 8.7 Options for LaTeX output....................................... 101 8.8 Options for text output........................................ 107 8.9 Options for manual page output................................... 107 8.10 Options for Texinfo output...................................... 108 8.11 Options for QtHelp output...................................... 109 8.12 Options for the linkcheck builder.................................. 109 8.13 Options for the XML builder..................................... 110 8.14 Options for the C++ domain..................................... 110 9 Example of configuration file 113 10 Internationalization 121 10.1 Sphinx internationalization details.................................. 122 10.2 Translating with sphinx-intl...................................... 123 10.3 Using Transifex service for team translation............................ 124 10.4 Contributing to Sphinx reference translation............................ 126 11 HTML theming support 127 11.1 Using a theme.............................................. 127 11.2 Builtin themes............................................. 128 11.3 Creating themes............................................ 132 ii 11.4 Distribute your theme as a python package............................. 133 11.5 Third Party Themes.......................................... 134 12 Setuptools integration 135 12.1 Using setuptools integration..................................... 135 12.2 Options for setuptools integration.................................. 136 13 Templating 139 13.1 Do I need to use Sphinx’s templates to produce HTML?..................... 139 13.2 Jinja/Sphinx Templating Primer................................... 139 13.3 Working with the builtin templates................................. 140 14 LaTeX customization 145 14.1 Basic customization.......................................... 145 14.2 The LaTeX style file options...................................... 146 14.3 LaTeX macros and environments................................... 149 15 Markdown support 153 15.1 Configuration.............................................. 153 16 Sphinx Extensions 155 16.1 Builtin Sphinx extensions....................................... 155 16.2 Third-party extensions......................................... 190 17 Developing extensions for Sphinx 191 17.1 Discovery of builders by entry point................................. 191 17.2 Extension metadata.......................................... 192 17.3 APIs used for writing extensions................................... 192 18 Sphinx Web Support 221 18.1 Web Support Quick Start....................................... 221 18.2 The WebSupport Class......................................... 225 18.3 Search Adapters............................................ 226 18.4 Storage Backends............................................ 226 19 Sphinx FAQ 229 19.1 How do I.................................................. 229 19.2 Using Sphinx with............................................. 230 19.3 Epub info................................................ 231 19.4 Texinfo info............................................... 232 20 Glossary 235 21 Sphinx Developer’s Guide 237 21.1 Bug Reports and Feature Requests.................................. 238 21.2 Contributing to Sphinx........................................ 238 21.3 Coding Guide.............................................. 241 21.4 Deprecating a feature......................................... 242 21.5 Deprecation policy........................................... 242 21.6 Unit Testing............................................... 242 22 Changes in Sphinx 245 22.1 Release 1.7 (in development)..................................... 245 22.2 Release 1.6.6 (in development).................................... 247 22.3 Release 1.6.5 (released Oct 23, 2017)................................. 247 22.4 Release 1.6.4 (released Sep 26, 2017)................................. 248 iii 22.5 Release 1.6.3 (released Jul 02, 2017).................................. 249 22.6 Release 1.6.2 (released May 28, 2017)................................. 249 22.7 Release 1.6.1 (released May 16, 2017)................................. 250 22.8 Release 1.6 (unreleased)........................................ 255 22.9 Release 1.5.6 (released May 15, 2017)................................. 256 22.10 Release 1.5.5 (released Apr 03, 2017)................................. 256 22.11 Release 1.5.4 (released Apr 02, 2017)................................. 256 22.12 Release 1.5.3 (released Feb 26, 2017)................................. 257 22.13 Release 1.5.2 (released Jan 22, 2017)................................. 258 22.14 Release 1.5.1 (released Dec 13, 2016)................................. 259 22.15 Release 1.5 (released Dec 5, 2016)................................... 260 22.16 Release 1.4.9 (released Nov 23, 2016)................................. 266 22.17 Release 1.4.8 (released Oct 1, 2016).................................. 266 22.18 Release 1.4.7 (released Oct 1, 2016).................................. 266 22.19 Release 1.4.6 (released Aug 20, 2016)................................. 267 22.20 Release 1.4.5 (released Jul 13, 2016).................................. 268 22.21 Release 1.4.4 (released Jun 12, 2016)................................. 269 22.22 Release 1.4.3 (released Jun 5, 2016).................................. 269 22.23 Release 1.4.2 (released May 29, 2016)................................. 270 22.24 Release 1.4.1 (released