Customizing reStructuredText (rst) for Domain-specific Syntax
=============================================================

- document tree

  - created by a ``Parser`` component (i.e. from reStructuredText input)
  - manually constructed

- ``docutils`` components

  - ``Reader``: Intended to obtain input and pass it to a ``Parser``.
  - ``Parser``: Generates a (docutils) document tree from a ``Reader`` input. docutils contains only a reStructuredText parser but potentially others may exists (e.g. markdown, html, etc.).
  - ``Writer``: Turns a document tree into an output (e.g. html, LaTeX).

- other "pieces"

  - transforms: Called by a ``Parser`` for on-the-fly document tree manipulation.
  - visitors: Operate on an existing document tree (i.e. after parsing). Can collect various information and/or manipulate the document tree.
  - roles: ??? https://docutils.sourceforge.io/docs/ref/rst/roles.html (see example that creates a custom ``date`` role as alternative to a ``date::`` directive https://docutils.sourceforge.io/docs/ref/rst/directives.html#date)
  - directives: ???

Custom Roles
------------

Custom Directives
-----------------

https://docutils.sourceforge.io/docs/ref/rst/directives.html

Directives have the following syntax::

  +-------+-------------------------------+
  | ".. " | directive type "::" directive |
  +-------+ block                         |
          |                               |
          +-------------------------------+

Examples::

  .. image:: /path/to/image.png
  
  .. figure:: /path/to/image.png
     :width: 600px
  
  .. note:: This is the note's 1st paragraph
     that spans multiple lines.
  
     This the note's 2nd paragraph.
     
     Notes are general blocks and can embed usual markup elements:
     
     * text elements with inline markup
     * list elements
     * other directives

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives

howto: https://docutils.sourceforge.io/docs/howto/rst-directives.html