Software Documentation is Important

Documentation is the core of good software development. You can write the best code and tools, but if the code is not documented, it will limit peoples’ use. In this lesson we will explore documentation as it relates to individual functions in Python.

There are two core components of a well documented function when writing software.

1. The Function Docstring

The docstring is the text that you write that describes the function inputs, outputs and application. It’s also the text that you or someone else will see when you use the help(function-name-here) function in python. Imagine what someone needs to know to use this function. This information should be included in the function docstring. This text goes within the function right below where it is defined. Like this:

def some-function(val):
“””
This is the docstring where you can document a function. This is what appears to describe the function when you type help(function-name) into the Python console.
parameters
--------------
   Val: int
        An integer that you wish to add 1 to.
“””
    newval = val+1
    return(newval)

Pay close attention to the syntax applied to the function above. You will see many different conventions surrounding how to format functions. We will be using PEP8 and the rasterio package as a guideline for syntax.

2. Online Package Documentation

Docstrings are the first step towards documenting code and proper online documentation is the second. However, good documentation can make or break good software. Proper software documentation is often on a separate website. For many python packages, readthedocs.org is used to host documentation. ReadTheDocs is free, easy to use and integrates easily with GitHub.

Good documentation will describe the functionality of the package. It will also provide easy to understand vignettes that demonstrate how parts of the package - e.g. functions are used. The more applied the vignettes are, the better. Some developers will even provide example workflows that show you how a set of functions in the package can be used together to produce an entire workflow.

As you begin to study the earthpy documentation, consider exploring other tools’ documentation for other examples of what documentation can look like. Some examples are below:

• earthpy documentation
• rasterio documentation
• geopandas documentation
• scikit learn docs - note this is not readthedocs documentation but still excellent!