.. toctree::

================
reStructuredText
================

reStructuredText (reST) is a markup language. The developers of
many projects, including Python, use it to write documentation.
It's also what I'm using to write this website. It has unobtrusive
syntax similar to Markdown, while supporting many things you would
otherwise need HTML for.

I'll be primarily referencing the `reStructuredText Primer`_.

.. _`reStructuredText Primer`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

~~~~~~~~~~
The basics
~~~~~~~~~~

If you've written Markdown before, the basic concept is similar.
A reStructuredText document is a plain text file, typically with
the .rst file extension. A paragraph can continue across multiple
lines, with a blank line between paragraphs.

Headings
--------

A heading is a line of text underlined, and optionally overlined,
with a punctuation symbol of your choice. As long as you're
consistent about what style you use for each level heading, they
can be pretty much anything you want, though there are
`conventions you can follow`_ if you like. If you're wondering,
this is what I use:

.. code-block:: rst

  =========
  Heading 1
  =========
  
  ~~~~~~~~~
  Heading 2
  ~~~~~~~~~
  
  Heading 3
  ---------

I haven't used a fourth-level heading yet, but I'd probably
underline it with carets.

.. _`conventions you can follow`: https://shawnjburke.github.io/py_guide/themes/sphinxdoc/reStructuredText/reStructuredText-CheatSheet-Headings.html

~~~~~
Links
~~~~~

Mark up the text within a paragraph that you want a link attached 
to, and put the link itself after the paragraph.

.. code-block:: rst

  This is the first paragraph. Here is an `example of a link`_.
  It will become clickable when the page is rendered.
  
  .. _`example of a link`: https://example.com/

Internal links
--------------

In `Sphinx`_ (the static site generator I use), `headings 
generate an anchor`_ similarly to how they do in Markdown on many 
platforms.

.. _`Sphinx`: ./sphinx.html
.. _`headings generate an anchor`: https://www.luisllamas.es/en/how-to-use-links-in-markdown/#internal-links
  
Footnotes
---------

There are a few different `ways to use footnotes`_, but here's
the one I find most flexible.

.. _`ways to use footnotes`: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes

.. code-block:: rst

  Here is a reference to the first footnote[#example]_. When the
  page is rendered, it will be labeled as "[1]". This is a 
  reference to a different footnote[#another]_, which will be
  labeled as "[2]". This one refers to the first footnote 
  again[#example]_, so it will also be labeled "[1]".
  
  .. rubric:: Footnotes
  
  .. [#example] https://example.com/
  .. [#another] This is another footnote.

.. note:: The ``.. rubric::`` directive creates a heading that
   won't appear in the table of contents.

~~~~~~~~~~~~~~~~
Formatted blocks
~~~~~~~~~~~~~~~~

Code
----

The blank line between the ``code-block::`` directive and the beginning 
of the actual code is necessary, as is the indentation of the 
actual code block. Specifying the language and caption are 
optional.

.. code-block:: rst

  .. code-block:: python
    :caption: hello.py
  
    name = 'reST'
    print('Hello ' + name + '!')

.. tip:: Syntax highlighting can be applied for any of the 
  `languages Pygments supports`_, and `other formatting options`_ 
  are available.
  
  .. _`languages Pygments supports`: https://pygments.org/languages/
  .. _`other formatting options`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code


Notices
-------

Any of the following keywords can be used. Themes may have their
own styles for each.

- note
- tip
- hint
- seealso
- attention
- important
- caution
- danger
- warning
- error

.. code-block:: rst

  .. attention:: This is a message.
    This text is part of the same message.
	
  This is a new paragraph.