THIS CONTENT IS MOVING!

We are moving our course lessons to an improved textbook series. All of the same content will be improved and available by the end of Spring 2020. While these pages will automagically redirect, you can also visit the links below to check out our new content! Our course landing pages with associated readings and assignments will stay here so you can continue to follow along with our courses!

Lesson 3. Introduction to Documenting Python Software


Learning Objectives

After completing this tutorial, you will be able to:

  • Be able to define what a Python function docstring is and the elements that should be included in a docstring.
  • Be able to describe the elements of a well documented python function.

What You Need

You will need a computer with internet access to complete this lesson.

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:

Leave a Comment