After completing this tutorial, you will be able to:
- Be able to create headings, lists and code blocks using the RST format
What You Need
You will need a computer with internet access to complete this lesson.
Introduction to ReStructured Text (RST)
You will find that many open source Python packages use <a href=”https://readthedocs.org/” target = “_blank”>Readthedocs</a> and restructured text (RST) to create their documentation. Readthedocs can accept markdown as a documentation format however,
RST is much more flexible.
The good news is that if you already know markdown, learning to work with
RST isn’t a huge leap. The structure is a bit different. Below are a few examples of how to create headers and lists with RST. This should be enough for you to submit documentation to the earthpy package.
Headers are created by using a symbol below the text for the header. The symbol should be repeated and should equal the same number of characters as the header text. You will notice that in some packages the header symbol isn’t the same length as the header text. However, we will follow the convention that it should be for all
Main Section Header ================ Subsection Header --------------------------
Lists are created in a similar fashion to listed in markdown. You can use a
- symbol to create a list. If you indent that dash, then you have a list sub item.
- A bulleted list item - Second item - A sub item - Spacing between items creates separate lists - Third item
Enumerated (Numbered) Lists
Enumerated or numbered lists are created using a number just like in markdown. However, you will add a
) after than number for it to render properly.
1) An enumerated list item 2) Second item a) Sub item that goes on at length and thus needs to be wrapped. Note that the indentation must match the beginning of the text, not the enumerator. i) List items can even include paragraph breaks. 3) Third item #) Another enumerated list item #) Second item
Code & Code Blocks
Code blocks in
.Rst are created using the syntax
.. code-block:: python
where the name of the coding language used in the block is specified.
.. code-block:: python >>> with rio.open('example.tif') as src: >>> im = src.read()
If you want to highlight code inline (within a text paragraph for instance), you can use two ticks on either side like this:
Here is a sentence with some code in it - ``es.crop_image()`` and the sentence continues