Tuto Documentation Release 0.1.0 DevOps people 2020-05-09 09H16 CONTENTS 1 Documentation news 3 1.1 Documentation news 2020........................................3 1.1.1 New features of sphinx.ext.autodoc (typing) in sphinx 2.4.0 (2020-02-09)..........3 1.1.2 Hypermodern Python Chapter 5: Documentation (2020-01-29) by https://twitter.com/cjolowicz/..................................3 1.2 Documentation news 2018........................................4 1.2.1 Pratical sphinx (2018-05-12, pycon2018)...........................4 1.2.2 Markdown Descriptions on PyPI (2018-03-16)........................4 1.2.3 Bringing interactive examples to MDN.............................5 1.3 Documentation news 2017........................................5 1.3.1 Autodoc-style extraction into Sphinx for your JS project...................5 1.4 Documentation news 2016........................................5 1.4.1 La documentation linux utilise sphinx.............................5 2 Documentation Advices 7 2.1 You are what you document (Monday, May 5, 2014)..........................8 2.2 Rédaction technique...........................................8 2.2.1 Libérez vos informations de leurs silos.............................8 2.2.2 Intégrer la documentation aux processus de développement..................8 2.3 13 Things People Hate about Your Open Source Docs.........................9 2.4 Beautiful docs.............................................. 10 2.5 Designing Great API Docs (11 Jan 2012)................................ 10 2.6 Docness.................................................. 10 2.6.1 Docness Source code...................................... 10 2.7 Hacking distributed (february 2013)................................... 10 2.8 Jacob Kaplan-Moss (November 10, 2009)................................ 11 2.9 Agile documentation best practices................................... 11 2.10 Best Practices for Documenting Technical Procedures Melanie Seibert................ 11 2.11 Plone................................................... 12 2.12 Twilio................................................... 12 2.13 Other advices............................................... 12 2.13.1 Write the docs.......................................... 12 2.13.2 Mindshare............................................ 15 3 Documentation generators 17 3.1 Sphinx .................................................. 17 3.1.1 Description........................................... 18 3.1.2 Sphinx source code (Sphinx dev guide)............................ 18 3.1.3 Sphinx applications....................................... 19 3.1.4 reST Sphinx........................................... 24 i 3.1.5 Sphinx extensions (sphinx.ext.*) ................................ 75 3.1.6 Sphinx contributed extensions................................. 88 3.1.7 Sphinx howto.......................................... 114 3.1.8 Sphinx examples........................................ 115 3.1.9 Sphinx i18n........................................... 135 3.1.10 Sphinx builders......................................... 135 3.1.11 Sphinx installation....................................... 137 3.1.12 Sphinx usage.......................................... 140 3.1.13 Sphinx people.......................................... 142 3.1.14 Sphinx tutorials......................................... 145 3.1.15 Tools for Sphinx........................................ 147 3.1.16 Sphinx themes......................................... 152 3.1.17 Sphinx templating........................................ 167 3.1.18 Sphinx translations....................................... 170 3.1.19 Sphinx versions......................................... 172 3.2 Authorea................................................. 186 3.2.1 Introduction........................................... 187 3.3 Doxygen................................................. 187 3.3.1 Introduction........................................... 187 3.3.2 Example............................................. 188 3.3.3 Doxygen source code...................................... 188 3.3.4 Issues, bugs, requests, ideas................................... 188 3.3.5 Projects using doxygen..................................... 189 3.3.6 Doxygen formats........................................ 196 3.3.7 Doxygen versions........................................ 196 3.4 gatsby (Build blazing fast, modern apps and websites with React), graphQL Foundation member... 202 3.5 Hugo (The world’s fastest framework for building websites)...................... 202 3.5.1 README.md.......................................... 203 3.5.2 Versions............................................. 207 3.6 Javadoc.................................................. 207 3.6.1 Introduction........................................... 207 3.7 Jekyll................................................... 208 3.7.1 Overview............................................ 208 3.7.2 Tools.............................................. 208 3.8 JSDoc................................................... 209 3.8.1 Getting Started......................................... 209 3.8.2 Bootstrap themes........................................ 209 3.9 mdbook.................................................. 210 3.10 Mkdocs.................................................. 210 3.10.1 Overview............................................ 210 3.10.2 Themes............................................. 210 3.10.3 Nice docs............................................ 210 3.11 Pandoc .................................................. 211 3.11.1 Introduction........................................... 211 3.11.2 Pandoc source code....................................... 212 3.11.3 Pandoc Commands....................................... 213 3.11.4 Versions............................................. 213 3.12 pdoc (Auto-generate API documentation for Python projects)..................... 213 3.12.1 pdoc definition......................................... 214 3.12.2 pdoc examples......................................... 215 3.12.3 pdoc versions.......................................... 216 3.13 redoc................................................... 216 3.13.1 redoc definition......................................... 216 3.13.2 redoc versions.......................................... 223 ii 3.14 swagger-ui................................................ 224 3.14.1 swagger-ui definition...................................... 224 3.14.2 swagger-ui versions....................................... 224 4 Sphinx documentation hosting 227 4.1 Sphinx documentation on gitlab pages ................................. 227 4.1.1 Continuous deployment of the documentation......................... 227 4.2 Hébergement Sphinx sur github pages.................................. 228 4.3 Sphinx on Read the docs......................................... 228 4.3.1 Introduction........................................... 229 4.3.2 Read the docs on twitter.................................... 230 4.3.3 New theme (4th of november 2013).............................. 230 4.3.4 How to............................................. 231 4.3.5 Projects on Read the docs.................................... 234 5 Good documentation 243 5.1 cakephp documentation......................................... 243 5.2 Fastapi (from Sebastián Ramírez).................................... 243 5.2.1 https://dockerswarm.rocks/................................... 244 5.3 Mattermost................................................ 244 5.4 Passlib documentation.......................................... 244 5.5 pretalx (Conference planning tool: CfP, scheduling, speaker management)............... 244 5.5.1 conf.py............................................. 245 5.5.2 Contents............................................. 245 5.5.3 administrator.......................................... 245 5.5.4 Developer............................................ 245 5.5.5 API............................................... 245 5.5.6 Maintainer............................................ 245 5.5.7 Commit messages........................................ 245 5.6 Sfepy documentation........................................... 246 5.7 Shark documentation........................................... 246 6 Formats Documentation 247 6.1 Input formats............................................... 247 6.1.1 Markdown ........................................... 247 6.1.2 ReStructuredText format................................... 263 6.1.3 Tex / Latex........................................... 270 6.1.4 Textile.............................................. 271 6.2 Input/output formats........................................... 271 6.2.1 L’Extensible Markup Language (XML)............................ 271 6.3 Output formats.............................................. 272 6.3.1 Dash format........................................... 272 6.3.2 EPUB format.......................................... 272 6.3.3 Hypertext_Markup_Language (HTML) format........................ 273 6.3.4 Portable Document Format (PDF)............................... 273 6.3.5 Windows HTML Help format (or known as CHM)...................... 274 6.3.6 L’Extensible Markup Language (XML)............................ 275 7 Documentation projects 277 7.1 C Documentation projects........................................ 277 7.1.1 clang (doxygen)......................................... 277 7.2 Mozilla documentation.......................................... 277 7.3 Documenting python projects.....................................