reStructuredText Sphinx concepts and syntax

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.

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

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

• https://restructuredtext.documatt.com/

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

• https://docs.anaconda.com/restructuredtext/detailed/

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

• https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html

• https://pradyunsg.me/furo/reference/

• reStructuredText Primer
  • Introduction
    • Paragraphs
    • Inline markup
    • Lists and Quote-like blocks
    • Literal blocks
    • Doctest blocks
    • Tables
    • Hyperlinks
      • External links
      • Internal links
    • Sections
    • Field Lists
    • Roles
    • Explicit Markup
    • Directives
    • Images
    • Footnotes
    • Citations
    • Substitutions
    • Comments
    • HTML Metadata
    • Source encoding
    • Gotchas
• reStructuredText (RST, ReST, or reST) Cheatsheet
  • Définition en français
  • Définition en anglais
  • Markups description
    • Inline Markup
    • Escaping with Backslashes
    • Lists
    • Section Structure
    • Blocks
    • Tables
    • Explicit Markup
    • Credits
• conf.py Examples
  • Introduction
  • pypi Example
  • Exclude patterns
    • exclude_patterns
  • Conf.py file for this project
• sphinx code
  • autodoc
  • literalinclude
    • rst:directive:: .. literalinclude:: filename
      • .. literalinclude::
    • :linenos:
    • :lineno-start:
    • :diff:
    • :caption:
    • :emphasize-lines:
    • :lines: xxx
    • :encoding: latin-1
    • :start-after: and :end-before:
      • Bash Example
      • Python examples
    • :start-at: and :end-at:
      • Common File Formats
    • :pyobject: xxx
    • :language: python
  • Documenting parameters
    • Example documenting parameters
      • Constants
      • COMMAND_SUCCESS
      • List of error codes
      • CR_RFID_VerifierPIN
• code-block (pygments, highlight)
  • Default highlighter
  • python highlighter
  • xml highlighter
  • console highlighter
  • ini highlighter
  • pycon python console highlighter
  • highlighting mode for the whole document
• Comments
• Sphinx Directives
• 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
    • sphinx C++ domain
      • The C++ Domain
      • These roles link to the given object types
• Explicit Markup
• figure
  • Description
  • Size in points (PDF constraints)
  • Geoserver example
• Sphinx Footnotes
• Sphinx Hyperlinks
  • External links
  • Internal links
• include
• Image
  • image
• 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)
      • .. index::
    • ! exclamation (important)
    • only : including content based on tags
      • Description
      • Example1
    • 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
      • .. deprecated::
    • hlist
      • .. hlist::
    • note
    • versionadded
    • versionchanged
      • .. versionchanged::
    • warning
• Paragraphs
• Lists
  • Description
  • Nested lists
  • Definition lists
  • list-table
• Sphinx raw html
  • Embedding a video
  • <ins>awsome</ins>
  • <del>awsome</del>
  • There is <del>nothing</del> <ins>no code</ins> either good or bad, but <del>thinking</del> <ins>running it</ins> makes it so
  • Raw data can also be read from an external file
  • <p style="color:red;">I am red</p>
  • <p style="background-color:yellow;">This is a paragraph.</p>
  • <p style="color:red;"><del>I am red</del></p>
  • <p style="color:green;">I am green</p>
  • <p class="gras vert">paragraphe gras et vert.</p>
  • <p class="rajout_vert">I am class green</p>
• Source Code
• Source encoding
• sidebar
• Sphinx Sections
  • Explicit Markup
  • Directives
  • Footnotes
  • Comments
  • Source encoding
  • Gotchas
• Substitution
  • Substitutions
  • conf.py
  • Use of rst_prolog
• toctree
• Tables
  • csv tables
    • Example 1
    • Example 2
  • grid tables
    • Two forms of tables are supported.
      • Examples
    • Grid table generator (https://www.tablesgenerator.com/text_tables)
  • list-table
    • Description
    • Exemple
      • Exemple 1
      • Example 2
      • Example 3
  • flat-table (needs linuxdoc extension, 2016-2017)
    • Requirements
    • flat-table
  • Rest Simple tables
• Tutorials
  • Good

Tools for Sphinx

• ReStructuredText tools
  • Hovercraft
    • Hovercraft Documentation
    • Hovercraft source code
    • Announce
    • Hovercraft!
    • Demo
    • Hovercraft news
  • http://rst.ninjs.org
• Why reStructuredText and not markdown (2016)
  • Adam Chainz