RST Primer
##########



Native Markup
*************

.. Paragraphs {{{

Paragraphs 
==========

..  rest-example::

    And the Lord spake, saying, 'First shalt thou take out the Holy Pin.
    Then, shalt thou count to three. No more. No less. Three shalt be the
    number thou shalt count, and the number of the counting shall be
    three. Four shalt thou not count, neither count thou two, excepting
    that thou then proceed to three. Five is right out. Once at the number
    three, being the third number be reached, then, lobbest thou thy Holy
    Hand Grenade of Antioch towards thy foe, who, being naughty in My
    sight, shall snuff it.'


..  }}}

..  Inline markup {{{

Inline markup
=============

..  rest-example::
    
   *text*
   **text**
   ``text``
   thisis\ *one*\ word


.. }}}

.. Lists {{{

Lists
=====

..  rest-example::

    * This is a bulleted list.
    * It has two items, the second
      item uses two lines
    
        * nested list
        * with some subitems
    
    * parent list continues
    
    #. Numbered list
    #. with two items
    
    
    10. I'll tell thee everything I can:
    #. There's little to relate.
    #. I saw an aged aged man,
    #. A-sitting on a gate.
    #. "Who are you, aged man?" I said,
    #. "And how is it you live?"
    #. And his answer trickled through my head,
    #. Like water through a sieve.
    
    i. He said "I look for butterflies
    #. That sleep among the wheat:
    #. I make them into mutton-pies,
    #. And sell them in the street.
    #. I sell them unto men," he said,
    #. "Who sail on stormy seas;
    #. And that's the way I get my bread—
    #. A trifle, if you please.

..  }}}

.. Definition List {{{

Definition List
===============

..  rest-example::


    **term** (up to a line of text)
        Definition of the text must be indented
    
    another term
    and the description

..  }}}

.. Quoted paragrap {{{

Quoted paragraph
================

..  rest-example::


    The instructions for the use of the Holly Grenade of Antioch

        And the Lord spake, saying, 'First shalt thou take out the Holy Pin. Then,
        shalt thou count to three. No more. No less. Three shalt be the number
        thou shalt count, and the number of the counting shall be three. Four
        shalt thou not count, neither count thou two, excepting that thou then
        proceed to three. Five is right out. Once at the number three, being the
        third number be reached, then, lobbest thou thy Holy Hand Grenade of
        Antioch towards thy foe, who, being naughty in My sight, shall snuff it.'

    The original version

..  }}}

.. Line Block {{{

Line Block
==========

..  rest-example::

    | I'll tell thee everything I can:
    | There's little to relate.
    | I saw an aged aged man,
    | A-sitting on a gate.
    | "Who are you, aged man?" I said,
    | "And how is it you live?"
    | And his answer trickled through my head,
    | Like water through a sieve.

..  }}}

.. Tables {{{

Tables
======

Grid Tables
-----------

+------------------------+------------+----------+----------+
| Header row, column 1   | Header 2   | Header 3 | Header 4 |
| (header rows optional) |            |          |          |
+========================+============+==========+==========+
| body row 1, column 1   | column 2   | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2             | ...        | ...      |          |
+------------------------+------------+----------+----------+


Simple Tables
-------------

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False
True   False  False
False  True   False
True   True   True
=====  =====  =======

CSV Tables
----------

.. csv-table:: Frozen Delights!
   :header: "Treat", "Quantity", "Description"
   :widths: 15, 10, 30

   "Albatross", 2.99, "On a stick!"
   "Crunchy Frog", 1.49, "If we took the bones out,
   it wouldn't be crunchy, now would it?"
   "Gannet Ripple", 1.99, "On a stick!"

List Tables
-----------

.. list-table:: Frozen Delights!
   :widths: 15 10 30
   :header-rows: 1

   * - Treat
     - Quantity
     - Description
   * - Albatross
     - 2.99
     - On a stick!
   * - Crunchy Frog
     - 1.49
     - If we took the bones out, it wouldn't be
       crunchy, now would it?
   * - Gannet Ripple
     - 1.99
     - On a stick!

Table with a title
------------------

.. table:: Truth table for "not"
   :widths: auto

   =====  =====
     A    not A
   =====  =====
   False  True
   True   False
   =====  =====

..  }}}

.. Hyperlinks {{{

Hyperlinks
==========

..  code-block:: rst

    text

Named
-----

This is a paragraph that contains  `a link`_. And one more to the
`cooking`_.

..  _a link: https://hugli.co.uk/docs/launchpad/
..  _cooking: https://hugli.co.uk/docs/cooking/

Anonymous
---------


Sphinx reStructured Text `primer <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__

Anonymous

..  }}}

.. Sections {{{

Sections
========

..  code-block:: rst

    text

..  todo::

    This needs attention:

    ::

    | L1 Section ##########
    | L2 Section **********
    | L3 Section ==========
    | L4 Section -----------
    | L5 Section ^^^^^^^^^^^
    | L6 Section """""""""""

..  }}}

.. Roles  {{{

Roles 
=====

..  code-block:: rst

    text

:emphasis:`italics`

:strong:`bold`

:literal:`literal`

X :subscript:`subscript`

X :superscript:`superscript`

:title-reference:`title-reference`

..  }}}

.. Images {{{

Images
======

..  code-block:: rst

    text

..  image:: https://hugli.co.uk/static/polls/images/background.jpg
..  image:: _static/background.png

..  }}}

.. Substitutions {{{

Substitutions
=============

..  code-block:: rst

..  |name| replace:: replacement *text*


Longer text with |name| in it.


..  }}}

.. Admonitions {{{

Admonitions
===========

..  code-block:: rst

    text

..  admonition:: Lemon Curry

    text

..  attention:: OTHER
..  caution:: |name|
..  danger:: text
..  error:: text
..  hint:: text
..  important:: text
..  note:: text
..  tip:: text
..  warning:: text

..  }}}

.. code-block {{{

code-block
==========

..  code-block:: python

    print("hello world")
    

..  literalinclude:: ../make.bat
    :caption: make for windows
    :language: batch
    :linenos:



..  }}}

.. Footnotes {{{

Footnotes & Citations
=====================

..  code-block:: rst

And the Lord spake, saying, 'First shalt thou take out the Holy Pin. Then,
shalt thou [#f1]_ count to three. No more. No less. Three shalt be the number
thou shalt count, and the number of the counting shall be three. Four
shalt thou not count, neither [#f2]_ count thou two, excepting that thou then
proceed to three. Five [Pears]_ is right out. Once at the number three, being the
third number be reached, then, lobbest thou thy Holy Hand Grenade of
Antioch towards thy foe, who, being naughty in My sight, shall snuff it.'

..  [Pears] Pears, R. and Shields, G. (2019) **Cite them right**: The essential
   referencing guide. 11th edn. London: MacMillan


..  }}}

Extended Markup
***************

.. Collapse {{{

Collapse
========

..  rest-example::

    .. collapse:: text

       .. literalinclude:: _static/test.py
    
       .. graphviz::
       
       	# "I played some days with making an interface between our ConceptBase
           # system (essentially a database system to store models) and graphviz. One
           # example graph is attached. It is a so-called petri net for Dutch traffic
           # lights. The example is actually taken from a book by Wil van der Aalst."
           # Contributed by Manfred Jeusfeld.
           
           ##Command to produce the output: "neato -Tpng thisfile > thisfile.png"
           
           digraph TrafficLights {
           fontname="Helvetica,Arial,sans-serif"
           node [fontname="Helvetica,Arial,sans-serif"]
           edge [fontname="Helvetica,Arial,sans-serif"]
           layout = neato
           node [shape=box];  gy2; yr2; rg2; gy1; yr1; rg1;
           node [shape=circle,fixedsize=true,width=0.9];  green2; yellow2; red2; safe2; safe1; green1; yellow1; red1;
           gy2->yellow2;
           rg2->green2;
           yr2->safe1;
           yr2->red2;
           safe2->rg2;
           green2->gy2;
           yellow2->yr2;
           red2->rg2;
           gy1->yellow1;
           rg1->green1;
           yr1->safe2;
           yr1->red1;
           safe1->rg1;
           green1->gy1;
           yellow1->yr1;
           red1->rg1;
           
           overlap=false
           label="PetriNet Model TrafficLights\nExtracted from ConceptBase and layed out by Graphviz"
           fontsize=12;
           }

..  }}}


.. Graphviz {{{

Graphviz
========

Graph
-----


.. graphviz::
   
    graph {
   a -- b
   }



Digraph
-------

.. graphviz::
   
    digraph {
   a -> b
   }

.. graphviz::

  digraph {
    rankdir = LR
    h [label="Hello", shape=square, color="#ffffaf", style="rounded,filled"]
    w [label=World, shape=egg]

    h -> w [color=orange, penwidth=2, label=x]
  }


.. graphviz::

   digraph {
   splines=ortho
   node [ shape=record, style=rounded]
   rankdir=LR

   s1 [
   label= "a|b|<p1>c"
   ]

   s2 [
   label= "<p1>a|{<p2>b1|<p3>b2}|<p4>c"
   ]

   s1:p1 -> s2:p1 [label=1]
   s2:p4 -> s2:p2 [label=Q, radius=10]

  }


.. graphviz::

   graph G {
       layout=neato;
       node [shape=circle];
   
       A [pos="0,0!"];
       B [pos="2,0!"];
       C [pos="1,2!"];
       D [pos="1,1!"];
   }

.. graphviz::

   digraph{
       node [
           style=filled,
           fillcolor="#66aaff",
           color="#0044aa",
           shape=folder, 
           style="rounded,filled",
           height=0.5,
           penwidth=2,
           fixedsize=false
           ]
      local_static [label="~/Projects/Documentation/\*\*"]
      local_dynamic [label="~/Projects/Active/django-tutorial/"]
      server_docs [label="/var/www/docs/"]
      server_static [label="/var/www/static"]
      server_dynamic [label="/srv/hermes/"]




      node [
           style=filled,
           fillcolor="#00aa22",
           color="#004422",
           shape=egg, 
           style="rounded,filled",
           height=0.5,
           penwidth=2,
           fixedsize=false
           ]

    browser [label="Browser"]
     
      node [
           style=filled,
           fillcolor="#ffaa00",
           color="#ff4400",
           shape=cds, 
           style="rounded,filled",
           height=0.5,
           penwidth=2,
           fixedsize=false

       ]

     socket [label="/run/socket.sock"]



  subgraph cluster_local {
    label="Elmer";
    local_dynamic;
    local_static;
  }



  subgraph cluster_server {
    label="Hermes";
    server_static;
    server_docs;
    server_dynamic;
    socket;
  }


  { local_static, 
    local_dynamic,
    server_docs,
    server_static,
    socket
  } -> browser


  server_dynamic -> socket;
  server_dynamic -> server_static;
  local_dynamic -> server_dynamic;
  local_static -> server_docs;


   }
..  }}}





.. graphviz::

    digraph {
      compound=true
      node [ fontname="Handlee" ];
      subgraph cluster_frontend {
        label="Frontend";
        React;
        Bootstrap;
      }
          
      subgraph cluster_backend {
        label="Backend";
        expressjs;
        "aws-sdk";
      }
    
      React -> expressjs [ltail=cluster_frontend];
      expressjs -> "aws-sdk" [constraint=false];
    }



..  [#f1] Text of the first one
..  [#f2] second one

..  }}}


Spellcheck
==========