Search⌘ K
AI Features
Home
Courses
Quick Start Full Stack Web Development

Get More reST: Making Changes

Explore how to document Python functions using reStructuredText within docstrings. Understand how to format descriptions, parameters, return values, and custom fields in Sphinx to create clear, readable, and well-structured code 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.

Python 3.5
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 ...