RST Basic Structure
*******************

Useful rst summaries
   https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
   https://docutils.sourceforge.io/docs/user/rst/quickref.html



Normally, there are no heading levels assigned to certain characters as the structure
is determined from the succession of headings. However, it is better to stick to the same
convention throughout a project. For instance:

*  ``#`` for parts
*  ``*`` for chapters
*  ``=`` for sections
*  ``-`` for subsections
*  ``^`` for subsubsections
*  ``"`` for paragraphs



.. sidebar:: Sidebar Title
    :subtitle: Optional Sidebar Subtitle

    Subsequent indented lines comprise
    the body of the sidebar, and are
    interpreted as body elements.
    
    #. Apples
    #. Oranges
    #. Bananas
    #. Kiwis


Terms and Definitions
   Definition of the term, which must be indented

   and can even consist of multiple paragraphs

Another Term
   Description.


Some Order List:

#. Apples
#. Oranges
#. Bananas




.. warning:: This is a warning in a box


.. topic:: Your Topic Title

    Subsequent indented lines comprise
    the body of the topic, and are
    interpreted as body elements.


    
.. _some internal link:

Links
=====

This is an important resource:
   https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html#explicit-links


This is a `Inline link <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_

.. _some external link to Sphinx RST Docs: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

This is a paragraph containing, separate link declaration and usage `some external link to Sphinx RST Docs`_



This one is `some internal link`_ to theHeading **Links** above

Or another syntax: :ref:`some internal link`





Labels and References
=====================

https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html#my-target


Internal Links are also be done via labels and references. Labels are defined at headers
In this and other documents on this site

Reference to other docs, see below! :ref:`inline-grid`.

Linking to other headers in other pages
---------------------------------------

- :ref:`my target` Links to the other document, with the name of the header captured

- :ref:`External file target <my target>`. Links to the other document with our own link name

This is a normal text paragraph. The next paragraph is a **python** code sample::

   class SomeType:
      def __init__(self,name='Someone'):
      self.name = name
      pass
   
This is a normal text paragraph again. 


.. code-block:: bash

   function quit_all_screens {
      for k in $(screen -ls | python -m xbin.screen_split); do screen -S $k -X quit; done
      echo "successfully quit all active screens"
   }
   export -f quit_all_screens


   function update_host_detached {
      if   [[ $# -eq 0 ]]; then
         screen -dmS sx_$(hostname) bash -c "sudo apt -y update && sudo apt -y upgrade"
      elif [[ $# -eq 1 ]]; then
         ssh $1 "screen -dmS sx_$1 bash -c \"sudo apt -y update && sudo apt -y upgrade\""
      else
         echo "too many hosts"
      fi
   }
   export -f update_host_detached


.. _inline-grid:

Variable Testing in Bash
========================

+-----------------------+-------------+---------+------------+
| Expression in script  | name='fish' | name='' | unset name |
+=======================+=============+=========+============+
| test "$name"          | TRUE        | f       | f          |
+-----------------------+-------------+---------+------------+
| test -n "$name"       | TRUE        | f       | f          |
+-----------------------+-------------+---------+------------+
| test ! -z "$name"     | TRUE        | f       | f          |
+-----------------------+-------------+---------+------------+
| test ! "${name-x}"    | f           | TRUE    | f          |
+-----------------------+-------------+---------+------------+
| test ! "${name+x}"    | f           | f       | TRUE       |
+-----------------------+-------------+---------+------------+


.. caution::
    Be Careful not to give yourself away
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur in dolor id
    magna tincidunt accumsan. Orci varius natoque penatibus et magnis dis parturient montes,
    nascetur ridiculus mus. Aenean congue laoreet placerat. In nec consequat elit,
    quis pharetra sapien. Vestibulum nec fringilla nunc. Nam tempor dolor quis pulvinar
    pharetra. Aenean rhoncus venenatis consequat. Phasellus non scelerisque nisl.
    Suspendisse malesuada lorem vitae aliquam porttitor. Duis et dolor at neque
    ultricies condimentum eu sodales lorem. Donec aliquet nisl eu purus dignissim,
    ac bibendum ante condimentum. Suspendisse finibus, risus eu placerat aliquet,
    felis turpis dapibus diam, a vehicula urna risus ac leo.