Sphinx Documentation Version 4.0.0+/06c59d272 Georg Brandl mars 27, 2021 Table des matières 1 Using Sphinx 1 1.1 Pour commencer.............................................1 Setting up the documentation sources..................................2 Defining document structure.......................................2 Adding content..............................................3 Running the build............................................3 Documenting objects...........................................4 Basic configuration............................................4 Autodoc.................................................5 Intersphinx................................................6 More topics to be covered........................................6 1.2 Installer Sphinx..............................................6 Résumé..................................................6 Linux...................................................7 Debian/Ubuntu..........................................7 RHEL, CentOS..........................................7 Other distributions........................................7 macOS..................................................7 Homebrew............................................7 MacPorts.............................................7 Anaconda.............................................8 Windows.................................................8 Chocolatey............................................8 Other Methods..........................................8 Installation from PyPI..........................................8 Docker..................................................9 Installation from source.........................................9 1.3 reStructuredText............................................. 10 reStructuredText Primer......................................... 10 Paragraphs............................................ 10 Inline markup........................................... 10 Lists and Quote-like blocks.................................... 11 Literal blocks........................................... 12 Doctest blocks.......................................... 12 Tables............................................... 12 Hyperlinks............................................ 13 i Sections.............................................. 13 Field Lists............................................. 14 Roles............................................... 14 Explicit Markup......................................... 15 Directives............................................. 15 Images.............................................. 16 Notes de bas de page....................................... 17 Citations............................................. 17 Substitutions........................................... 18 Comments............................................ 18 HTML Metadata......................................... 18 Source encoding......................................... 19 Gotchas.............................................. 19 Roles................................................... 19 Cross-referencing syntax..................................... 19 Math............................................... 23 Other semantic markup...................................... 23 Substitutions........................................... 25 Directives................................................. 25 Table of contents......................................... 25 Paragraph-level markup..................................... 28 Showing code examples..................................... 30 Glossaire............................................. 35 Meta-information markup.................................... 36 Index-generating markup..................................... 36 Including content based on tags................................. 37 Tables............................................... 38 Math............................................... 39 Grammar production displays.................................. 40 Field Lists................................................ 41 File-wide metadata........................................ 41 Special metadata fields...................................... 41 Domains................................................. 42 Basic Markup........................................... 42 The Python Domain....................................... 44 The C Domain.......................................... 50 The C++ Domain......................................... 54 The Standard Domain...................................... 64 The JavaScript Domain...................................... 65 The reStructuredText domain................................... 67 The Math Domain........................................ 68 More domains.......................................... 68 1.4 Markdown................................................ 68 Configuration............................................... 69 1.5 Configuration............................................... 69 Informations sur le projet........................................ 70 Configuration générale.......................................... 70 Options pour l’internationalisation.................................... 77 Options for Math............................................. 80 Options pour la sortie HTML...................................... 80 Options for Single HTML output.................................... 87 Options for HTML help output..................................... 87 Options for Apple Help output...................................... 87 Options pour la sortie epub....................................... 89 ii Options pour la sortie LaTeX...................................... 92 Options pour la sortie text........................................ 94 Options for manual page output..................................... 95 Options pour la sortie Texinfo...................................... 95 Options pour la sortie QtHelp...................................... 97 Options for the linkcheck builder.................................... 97 Options for the XML builder....................................... 99 Options for the C domain........................................ 99 Options for the C++ domain....................................... 99 Options for the Python domain...................................... 100 Exemple de fichier de configuration............................... 100 1.6 Builders.................................................. 107 Détails du constructeur de la sérialisation................................ 114 1.7 Extensions................................................ 115 Built-in extensions............................................ 115 sphinx.ext.autodoc – Inclure la documentation des chaînes docstrings........... 115 sphinx.ext.autosectionlabel – Autoriser les sections de référence en utilisant son titre. 125 sphinx.ext.autosummary – Generate autodoc summaries.................. 125 sphinx.ext.coverage – Collecte les statistiques de couverture de doc............ 129 sphinx.ext.doctest – Test snippets in the documentation.................. 130 sphinx.ext.duration – Mesurer les durées de traitement du Sphinx............ 135 mod :`sphinx.ext.ext.extlinks” – Balisage pour raccourcir les liens externes.......... 135 sphinx.ext.githubpages – publie des documents HTML sur les pages GitHub...... 136 sphinx.ext.graphviz – Ajouter des graphiques Graphviz.................. 136 sphinx.ext.ifconfig – Inclure du contenu basé sur la configuration............ 139 sphinx.ext.ext.imgconverter – Un convertisseur d’image de référence utilisant Image- magick......................................... 139 sphinx.ext.inheritance_diagram – Inclure les diagrammes d’héritage.......... 140 mod :sphinx.ext.ext.intersphinx – Lien vers la documentation d’autres projets......... 142 sphinx.ext.linkcode – Ajouter des liens externes au code source............. 145 Math support for HTML outputs in Sphinx........................... 146 sphinx.ext.napoleon – Support for NumPy and Google style docstrings.......... 148 sphinx.ext.ext.todo – Prise en charge des éléments todo.................. 158 sphinx.ext.viewcode – Add links to highlighted source code................ 158 Extensions tierces............................................ 160 Où mettre vos propres extensions?................................ 160 1.8 HTML Theming............................................. 160 Builders.................................................. 160 Themes.................................................. 160 Using a theme.......................................... 161 Builtin themes.......................................... 162 Third Party Themes....................................... 165 1.9 Internationalization............................................ 166 Sphinx internationalization details.................................... 166 Translating with sphinx-intl....................................... 167 Quick guide............................................ 167 Translating............................................ 168 Update your po files by new pot files............................... 168 Using Transifex service for team translation............................... 168 Contributing to Sphinx reference translation.............................. 170 1.10 Intégration des outils d’installation................................... 170 Utilisation de l’intégration des outils de configuration......................... 170 Options for setuptools integration.................................... 171 1.11 Sphinx Web Support........................................... 173