Sphinx Documentation Release 1.5.4
Total Page:16
File Type:pdf, Size:1020Kb
Sphinx Documentation Release 1.5.4 Georg Brandl Apr 02, 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-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......................................... 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.4 (released Apr 02, 2017)................................. 237 23.2 Release 1.5.3 (released Feb 26, 2017)................................. 238 iii 23.3 Release 1.5.2 (released Jan 22, 2017)................................. 238 23.4 Release 1.5.1 (released Dec 13, 2016)................................. 240 23.5 Release 1.5 (released Dec 5, 2016)................................... 240 23.6 Release 1.4.9 (released Nov 23, 2016)................................. 246 23.7 Release 1.4.8 (released Oct 1, 2016).................................. 247 23.8 Release 1.4.7 (released Oct 1, 2016).................................. 247 23.9 Release 1.4.6 (released Aug 20, 2016)................................. 248 23.10 Release 1.4.5 (released Jul 13, 2016).................................. 248 23.11 Release 1.4.4 (released Jun 12, 2016)................................. 249 23.12 Release 1.4.3 (released Jun 5, 2016).................................. 250 23.13 Release 1.4.2 (released May 29, 2016)................................. 250 23.14 Release 1.4.1 (released Apr 12, 2016)................................. 252 23.15 Release 1.4 (released Mar 28, 2016).................................. 253 23.16 Release 1.3.6 (released Feb 29, 2016)................................. 257 23.17 Release 1.3.5 (released Jan 24, 2016)................................. 257 23.18 Release 1.3.4 (released Jan 12, 2016)................................. 258 23.19 Release 1.3.3 (released Dec 2, 2015).................................. 259 23.20 Release 1.3.2 (released Nov 29, 2015)................................. 259 23.21 Release 1.3.1 (released Mar 17, 2015)................................. 261 23.22 Release 1.3 (released Mar 10, 2015).................................. 261 23.23 Release 1.3b3 (released Feb 24, 2015)................................