Docstrings are used to document the code and produce Sphinx pages. We use the Docstring Conventions, known as “PEP 257”, as a starting point. Additionally, we use the Sphinx Python Domain to help organize the information. This page explains further details about our use of docstrings.
Return Option
If a function returns a value that is not None, there should be a :return: block, which should be no more than a couple of lines. If it needs to be longer, the details should be added in a general block below.
URL Handlers
Many functions in this system are URL handlers that are called indirectly. As such their parameters consist of the context created by the surrounding WSGI constructors and do not require separate documentation in each case. See the page on URL handlers for more information.
The summary line for URL handlers should end in “URL handler.” to make clear that the function is a URL handler. If there are both GET and POST handlers (or other HTTP methods), the summary line should end in “GET URL handler.” or “POST URL handler.” as appropriate.