Documentation Convention

This document states the convention that we follow for writing Documentation and especially docstrings for classes and functions for sosw package. This convention is based on PEP8, with minor styling changes listed below.

Basics

  • We use sphinx package to compile documentation.

  • We use sphinx.autodoc extention to automatically parse the Python code and extract docstrings.

  • .rst wins against .md

  • Make docstrings readable both in the code and in HTML. Use new lines and tabs to beautify the source of docstrings even if they are not really required.

  • Richard wins against Winnie.

Imports

import core modules
-*(empty line)*
import custom libraries
--
import custom modules
--
from core import something
--
from custom libraries import something
--
from custom modules import something
Within each of the blocks sort alphabetically.
Example:
import datetime
import time

import requests

from collections.defaultdict import defaultdict

from my_lib_abc.models import AwesomeModel
from my_lib_abc.qwerty import AwesomeClass

Building the docs

You can locally build the docs and use the built in python web server to view the html version directly from localhost in your preferred browser. Warnings are treated as errors (-W), exactly as in CI.

python -m sphinx -W -a -b html docs sosw-rtd; (cd sosw-rtd && python -m http.server)

Common Sense Boosters

  • Document for humans. You will have to read this one day later.

  • Read other good docs to notice some good practices.

  • Do not be afraid to use some new markup features not yet used in our documentation.

  • Create labels where required, if you feel that you will need it one day from other doc.

  • Do not make pull requests if your docstrings do not compile in Sphinx without warnings.

Structure

index.rst of each Lambda should reside in ./docs/. It should have the basic Readme information and links to the documentation of external components used in the Lambda. At the end of the file, you should include the autodoc directives for each module of your function (the minimum of app.py)

If you add schemas or images (good practice) include them in ./docs/images/ and use appropriately.

Example of Docstring

def hello(name, age, tags=None):
    """
    User friendly welcome function.
    Uses `name` and `age` to salute user.
    This is still same line of documentation.

    While this is a new paragraph.
    Note that `rst` is sensitive to empty lines and spaces.

    Some code Example:

    .. code-block:: python

        def hello():
            return "world"

    This is paragraph 3.

    * And some bullet list
    * With couple rows

    Now go parameters. PyCharm adds them automatically.

    :param str name:    User name of type string.
    :param tags:        Types are not required, but this is a good
                        practice to show what you expect.

    :param age:         You can also specify multiple types, with a
                        little different syntax.
                        Note that empty lines do not matter here for
                        `sphinx`, but good for code readability.
    :type age:          int | float

    :rtype:             dict
    :return:            You can specify type of return value in
                        `rtype` (if it is uncertain).
    """

    return f"Hello {'bro' if age > 10 else 'kid'}"

I hope this example above was useful. Note the indention and spacing again. Now we are out of code-block. Do not get frustrated with the 80 chars width that I used in the example. This is just to show this code-block nicely when displayed as code in rendered HTML. Our convention is 120 characters max width.

Here is the compiled version of the example docstring from above:

docs.hello.hello(name, age, tags=None)[source]

User friendly welcome function. Uses name and age to salute user. This is still same line of documentation.

While this is a new paragraph. Note that rst is sensitive to empty lines and spaces.

Some code Example:

def hello():
    return "world"

This is paragraph 3.

  • And some bullet list

  • With couple rows

  • Even 3 rows

Now go parameters. PyCharm adds them automatically.

Parameters:

  • name (str) – User name of type string.

  • tags – Types are not required, but this is a good practice to show what you expect.

  • age (int | float) – You can also specify multiple types, with a little different syntax. Note that empty lines do not matter here for sphinx, but good for code readability.

Return type:

dict

Returns:

You can specify type of return value in rtype (if it is uncertain).

End of the compiled example.