In This Lesson

Learning Objectives

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

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 earthpy documentation.

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