Part 3: Documentation

Writing it, building it, and publishing it automatically.

Why write it at all?

Code tells a computer what.

Documentation tells a human why.

Start with the README

_images/p3-readme.svg

reStructuredText

Features
________

#. Be awesome
#. Make things faster

Two things that will bite you

  • indentation is meaningful — get it wrong and a block silently stops belonging to the directive above it

  • blank lines matter, for the same reason

One source, many outputs

_images/p3-one-source-many-outputs.svg

The toctree wires it together

_images/p3-toctree.svg

Docstrings

def addition(arg1, arg2):
    """
    This function adds the first and the second argument.

    :param arg1: the first summand
    :return:     the sum of both summands
    """
    return arg1 + arg2

Why they live in the code

Change the function, update its documentation one line away.

autodoc: write once, appear twice

_images/p3-docstring-autodoc.svg

Publishing it automatically

_images/p3-webhook-cd.svg

Over to you

Write documentation, build it locally, then publish it and watch it rebuild on push.

Part 3 tasks →