After completing this tutorial, you will be able to:
- Be able to define what a
Pythonfunction 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: