Quick Start Full Stack Web Development/

...

/

Get More reST: Making Changes

Get More reST: Making Changes

Learn what reST is and how it creates fields in the documentation.

We'll cover the following...

What is reST?

The documentation strings in Python functions are interpreted as reStructured Text (reST). This is a markup language, like Markdown, that attempts to preserve readability. It includes both in-line markups, such as bold text, lists, and directives instructing the document generator to create special blocks, such as inserting images or a table of contents.

Making some changes

We can use reST to create fields in the documentation strings by surrounding a word with colons. Here is how we might document the post method.

Press + to interact
def post(self):
    """Post a new favorite number; server assigns the id
    Appends a favorite number with a description into the
    collection, assigning it a unique identifier. Returns the new identifier.
    :route: ``/my-api`` POST
    :payload:
       Submit a JSON object with:
          * ``number``: the new favorite number (int)
          * ``description``: reason it's a favorite (str)
    :error: **400** if missing either ``number`` or ``description`` field
    :return: Newly assigned identifier
"""
...

The documentation style chosen here was just one ...