Sphinx Documentation Release 1.2.3
Total Page:16
File Type:pdf, Size:1020Kb
Sphinx Documentation Release 1.2.3 Georg Brandl November 12, 2014 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 Setting up the documentation sources................................3 2.2 Defining document structure.....................................3 2.3 Adding content.............................................4 2.4 Running the build...........................................5 2.5 Documenting objects..........................................5 2.6 Basic configuration...........................................6 2.7 Autodoc.................................................6 2.8 Intersphinx...............................................7 2.9 More topics to be covered.......................................7 3 Invocation of sphinx-build9 3.1 Makefile options............................................ 11 4 Invocation of sphinx-apidoc 13 5 reStructuredText Primer 15 5.1 Paragraphs............................................... 15 5.2 Inline markup.............................................. 15 5.3 Lists and Quote-like blocks...................................... 16 5.4 Source Code............................................... 17 5.5 Tables.................................................. 18 5.6 Hyperlinks............................................... 18 5.7 Sections................................................. 18 5.8 Explicit Markup............................................ 19 5.9 Directives................................................ 19 5.10 Images.................................................. 21 5.11 Footnotes................................................ 22 5.12 Citations................................................. 22 5.13 Substitutions.............................................. 22 5.14 Comments................................................ 23 5.15 Source encoding............................................ 23 5.16 Gotchas................................................. 23 6 Sphinx Markup Constructs 25 i 6.1 The TOC tree.............................................. 25 6.2 Paragraph-level markup........................................ 28 6.3 Table-of-contents markup....................................... 30 6.4 Glossary................................................. 30 6.5 Grammar production displays.................................... 30 6.6 Showing code examples........................................ 31 6.7 Inline markup.............................................. 34 6.8 Miscellaneous markup......................................... 38 7 Sphinx Domains 43 7.1 What is a Domain?........................................... 43 7.2 Basic Markup.............................................. 43 7.3 The Python Domain.......................................... 44 7.4 The C Domain............................................. 49 7.5 The C++ Domain............................................ 50 7.6 The Standard Domain......................................... 51 7.7 The JavaScript Domain........................................ 52 7.8 The reStructuredText domain..................................... 53 7.9 More domains............................................. 54 8 Available builders 55 8.1 Serialization builder details...................................... 59 9 The build configuration file 61 9.1 General configuration......................................... 61 9.2 Project information........................................... 64 9.3 Options for internationalization................................... 65 9.4 Options for HTML output....................................... 67 9.5 Options for epub output........................................ 71 9.6 Options for LaTeX output....................................... 74 9.7 Options for text output........................................ 77 9.8 Options for manual page output................................... 77 9.9 Options for Texinfo output...................................... 78 9.10 Options for the linkcheck builder.................................. 79 9.11 Options for the XML builder..................................... 80 10 Internationalization 81 10.1 Sphinx internationalization details.................................. 82 10.2 Translating with sphinx-intl...................................... 83 10.3 Using Transifex service for team translation............................ 84 10.4 Contributing to Sphinx reference translation............................ 85 11 HTML theming support 87 11.1 Using a theme.............................................. 87 11.2 Builtin themes............................................. 90 11.3 Creating themes............................................ 93 12 Templating 95 12.1 Do I need to use Sphinx’ templates to produce HTML?...................... 95 12.2 Jinja/Sphinx Templating Primer................................... 95 12.3 Working with the builtin templates................................. 96 13 Sphinx Extensions 101 13.1 Builtin Sphinx extensions....................................... 101 13.2 Third-party extensions......................................... 124 ii 14 Developing extensions for Sphinx 125 14.1 Tutorial: Writing a simple extension................................. 125 14.2 Application API............................................ 131 14.3 Build environment API........................................ 139 14.4 Builder API............................................... 140 14.5 Docutils markup API......................................... 141 14.6 Domain API............................................... 143 14.7 Doctree node classes added by Sphinx................................ 146 15 Sphinx Web Support 149 15.1 Web Support Quick Start....................................... 149 15.2 The WebSupport Class......................................... 153 15.3 Search Adapters............................................ 156 15.4 Storage Backends............................................ 157 16 Sphinx FAQ 161 16.1 How do I.................................................. 161 16.2 Using Sphinx with............................................. 161 16.3 Epub info................................................ 162 16.4 Texinfo info............................................... 163 17 Glossary 165 18 Sphinx Developer’s Guide 167 18.1 Bug Reports and Feature Requests.................................. 167 18.2 Contributing to Sphinx........................................ 167 18.3 Coding Guide.............................................. 170 19 Changes in Sphinx 171 19.1 Release 1.2.3 (released Sep 1, 2014).................................. 171 19.2 Release 1.2.2 (released Mar 2, 2014)................................. 172 19.3 Release 1.2.1 (released Jan 19, 2014)................................. 172 19.4 Release 1.2 (released Dec 10, 2013).................................. 174 19.5 Release 1.2 beta3 (released Oct 3, 2013)............................... 175 19.6 Release 1.2 beta2 (released Sep 17, 2013)............................... 175 19.7 Release 1.2 beta1 (released Mar 31, 2013).............................. 177 19.8 Release 1.1.3 (Mar 10, 2012)...................................... 181 19.9 Release 1.1.2 (Nov 1, 2011) – 1.1.1 is a silly version number anyway!.............. 182 19.10 Release 1.1.1 (Nov 1, 2011)...................................... 182 19.11 Release 1.1 (Oct 9, 2011)........................................ 182 19.12 Release 1.0.8 (Sep 23, 2011)...................................... 184 19.13 Release 1.0.7 (Jan 15, 2011)...................................... 185 19.14 Release 1.0.6 (Jan 04, 2011)...................................... 186 19.15 Release 1.0.5 (Nov 12, 2010)...................................... 187 19.16 Release 1.0.4 (Sep 17, 2010)...................................... 187 19.17 Release 1.0.3 (Aug 23, 2010)...................................... 187 19.18 Release 1.0.2 (Aug 14, 2010)...................................... 187 19.19 Release 1.0.1 (Jul 27, 2010)....................................... 188 19.20 Release 1.0 (Jul 23, 2010)........................................ 188 19.21 Previous versions............................................ 191 20 Projects using Sphinx 193 20.1 Documentation using the default theme............................... 193 20.2 Documentation using a customized version of the default theme................ 194 20.3 Documentation using the sphinxdoc theme............................. 195 iii 20.4 Documentation using another builtin theme............................ 196 20.5 Documentation using a custom theme/integrated in a site.................... 196 20.6 Homepages and other non-documentation sites.......................... 198 20.7 Books produced using Sphinx.................................... 198 20.8 Thesis using Sphinx.......................................... 198 Python Module Index 199 Index 201 iv CHAPTER ONE INTRODUCTION This is the documentation for the Sphinx documentation builder. Sphinx is a tool that translates a set of reStructuredText1 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