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
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
The toctree wires it together
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
Publishing it automatically
Over to you
Write documentation, build it locally, then publish it and watch it rebuild on push.