Documentation tutorial

Documentation tutorial

Release

0.1.0

Date

2020-05-09 09H15

Authors

Devops people

Target

Tutorial about documentation

See also

• https://gitlab.com/gdevops

• https://gitlab.com/gdevops/tuto_documentation

• https://gdevops.gitlab.io/tuto_devops/

• http://blog.smartbear.com/software-quality/bid/256072/13-reasons-your-open-source-docs-make-people-want-to-scream

• http://brikis98.blogspot.de/2014/05/you-are-what-you-document.html

• http://redaction-technique.org/index.html

Our favorite document generator is sphinx and we use the reStructuredText markup.

• Documentation news
  • Documentation news 2020
    • New features of sphinx.ext.autodoc (typing) in sphinx 2.4.0 (2020-02-09)
    • Hypermodern Python Chapter 5: Documentation (2020-01-29) by https://twitter.com/cjolowicz/
  • Documentation news 2018
    • Pratical sphinx (2018-05-12, pycon2018)
    • Markdown Descriptions on PyPI (2018-03-16)
    • Bringing interactive examples to MDN
  • Documentation news 2017
    • Autodoc-style extraction into Sphinx for your JS project
  • Documentation news 2016
    • La documentation linux utilise sphinx
• Documentation Advices
  • You are what you document (Monday, May 5, 2014)
  • Rédaction technique
    • Libérez vos informations de leurs silos
    • Intégrer la documentation aux processus de développement
  • 13 Things People Hate about Your Open Source Docs
  • Beautiful docs
  • Designing Great API Docs (11 Jan 2012)
  • Docness
    • Docness Source code
  • Hacking distributed (february 2013)
  • Jacob Kaplan-Moss (November 10, 2009)
  • Agile documentation best practices
  • Best Practices for Documenting Technical Procedures Melanie Seibert
  • Plone
  • Twilio
  • Other advices
    • Write the docs
    • Mindshare
• Documentation generators
  • Sphinx
    • Description
    • Sphinx source code (Sphinx dev guide)
    • Sphinx applications
    • reST Sphinx
    • Sphinx extensions (sphinx.ext.*)
    • Sphinx contributed extensions
    • Sphinx howto
    • Sphinx examples
    • Sphinx i18n
    • Sphinx builders
    • Sphinx installation
    • Sphinx usage
    • Sphinx people
    • Sphinx tutorials
    • Tools for Sphinx
    • Sphinx themes
    • Sphinx templating
    • Sphinx translations
    • Sphinx versions
  • Authorea
    • Introduction
  • Doxygen
    • Introduction
    • Example
    • Doxygen source code
    • Issues, bugs, requests, ideas
    • Projects using doxygen
    • Doxygen formats
    • Doxygen versions
  • gatsby (Build blazing fast, modern apps and websites with React), graphQL Foundation member
  • Hugo (The world’s fastest framework for building websites)
    • README.md
    • Versions
  • Javadoc
    • Introduction
  • Jekyll
    • Overview
    • Tools
  • JSDoc
    • Getting Started
    • Bootstrap themes
  • mdbook
  • Mkdocs
    • Overview
    • Themes
    • Nice docs
  • Pandoc
    • Introduction
    • Pandoc source code
    • Pandoc Commands
    • Versions
  • pdoc (Auto-generate API documentation for Python projects)
    • pdoc definition
    • pdoc examples
    • pdoc versions
  • redoc
    • redoc definition
    • redoc versions
  • swagger-ui
    • swagger-ui definition
    • swagger-ui versions
• Sphinx documentation hosting
  • Sphinx documentation on gitlab pages
    • Continuous deployment of the documentation
  • Hébergement Sphinx sur github pages
  • Sphinx on Read the docs
    • Introduction
    • Read the docs on twitter
    • New theme (4th of november 2013)
    • How to
    • Projects on Read the docs
• Good documentation
  • cakephp documentation
  • Fastapi (from Sebastián Ramírez)
    • https://dockerswarm.rocks/
  • Mattermost
  • Passlib documentation
  • pretalx (Conference planning tool: CfP, scheduling, speaker management)
    • conf.py
    • Contents
    • administrator
    • Developer
    • API
    • Maintainer
    • Commit messages
  • Sfepy documentation
  • Shark documentation
• Formats Documentation
  • Input formats
    • Markdown
    • ReStructuredText format
    • Tex / Latex
    • Textile
  • Input/output formats
    • L’Extensible Markup Language (XML)
  • Output formats
    • Dash format
    • EPUB format
    • Hypertext_Markup_Language (HTML) format
    • Portable Document Format (PDF)
    • Windows HTML Help format (or known as CHM)
    • L’Extensible Markup Language (XML)
• Documentation projects
  • C Documentation projects
    • clang (doxygen)
  • Mozilla documentation
  • Documenting python projects
    • pep0257
    • Documenting python projects with sphinx
• Documentation tools
  • Dash
    • Description
    • Dash user contributions
    • Dash in doxygen
    • Sphinx dash builder
    • Zeal
    • Documentation Browser
  • diagrams
    • blockdiag
    • seqdiag
    • actdiag
    • nwdiag
    • interactive.blockdiag
  • Graphviz
    • What is Graphviz ?
    • Used by
  • pygments (generic syntax highlighter)
    • pygments definition
    • pygments FAQ
    • pygments formatters
    • pygments lexers
    • pygments styles
    • pygments issues
    • pygments pull requests
    • pygments releases
  • Zeal documentation browser
    • Description
    • Sphinx dash builder
• Documentation videos
  • Write the docs
  • RTFM - wRite The Friendly Manual
• Wiki documentation
  • Mediawiki
    • Introduction
    • The Wikimedia Foundation
    • API mediawiki
    • Developer hub mediawiki
    • Extensions mediawiki
    • International mediawiki
    • Projets utilisant mediawiki
    • Outils mediawiki
  • Wiki tools
    • Django wiki