reStructuredText Sphinx documentation

This section is a brief introduction to reStructuredText (reST) concepts and syntax, intended to provide authors with enough information to author documents productively.

Since reST was designed to be a simple, unobtrusive markup language, this will not take too long.

Date

2020-05-09 09H15

See also

• http://sphinx-doc.org/latest/index.html

• http://packages.python.org/an_example_pypi_project/sphinx.html

• http://docutils.sourceforge.net/rst.html

• http://rest-sphinx-memo.readthedocs.org/en/latest/ReST.html

• http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/_sources/source/sphinx/rest_syntax.txt

• http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html

• https://cjolowicz.github.io/posts/hypermodern-python-05-documentation/#writing-documentation-using-restructuredtext

• Sphinx

• conf.py Examples
  • Introduction
  • pypi Example
  • Exclude patterns
    • exclude_patterns
  • Conf.py file for this project
• sphinx markup
  • sphinx inline markup
    • abbr
    • doc
      • Introduction
      • Example 1 : local link
      • Example 2 : with explicit link text
      • Example 3 no explicit link text
    • command
    • download
    • glossary
    • guilabel
      • Example 1
      • Example 2 ampersand accelerators
    • menuselection
      • Introduction
      • Example 1
      • Example 2 ampersand accelerators
    • program
      • Example
    • term (very important)
  • sphinx misc markup (very important)
    • index (very important)
    • ! exclamation (important)
    • only : including content based on tags
      • Description
      • Example1
        • in conf.py
        • In a .rst file
    • pair (very important)
    • see
    • seealso
    • single
    • triple
    • Deprecated : module, keyword, operator, object, exception, statement, builtin
  • sphinx paragraph level markup
    • contents (très important)
      • Table-of-contents markup
      • Example 1
      • Example 2
    • deprecated
    • hlist
    • note
    • versionadded
    • versionchanged
    • warning
• sphinx domain
  • What is a Domain ?
  • Default Domain
  • primary_domain
    • sphinx C domain
      • C doc examples
      • C domain
      • C function
      • C member
      • C macro
      • C type (structure)
      • C var
      • Cross-referencing C constructs
        • Cross-referencing a variable
        • Cross-referencing a function
        • Cross-referencing a macro
        • Cross-referencing a structure
    • sphinx C++ domain
      • The C++ Domain
      • These roles link to the given object types
• sphinx code
  • autodoc
  • literalinclude
    • rst:directive:: .. literalinclude:: filename
    • :linenos:
    • :lineno-start:
    • :diff:
    • :caption:
    • :emphasize-lines:
    • :lines: xxx
    • :encoding: latin-1
    • :pyobject: xxx
    • :language: python
  • Documenting parameters
    • Example documenting parameters
      • Constants
      • COMMAND_SUCCESS
      • List of error codes
      • CR_RFID_VerifierPIN
• toctree
• Paragraphs
• Image
  • image
• figure
  • Description
  • Size in points (PDF constraints)
  • Geoserver example
• Substitution
  • Substitutions
• Lists
  • Description
  • Nested lists
  • Definition lists
  • list-table
• Source Code
• include
• code-block (pygments, highlight)
  • Default highlighter
  • python highlighter
  • xml highlighter
  • console highlighter
  • ini highlighter
  • pycon python console highlighter
  • highlighting mode for the whole document
• rest Tables
  • csv tables
  • Rest grid tables
    • Examples
  • list-table
    • Description
    • Exemple
      • Exemple 1
      • Example 2
      • Example 3
  • flat-table (needs linuxdoc extension, 2016-2017)
    • Requirements
    • flat-table
  • Rest Simple tables
• sphinx Hyperlinks
  • External links
  • Internal links
• Sphinx Sections
  • Explicit Markup
  • Directives
  • Footnotes
  • Comments
  • Source encoding
  • Gotchas
• Explicit Markup
• Sphinx Directives
• Sphinx Footnotes
• Comments
• Source encoding
• sidebar
• Gotchas