1. Documentation
A really important part of developing packages is writing documentation.
2. Why include documentation?
It can be tempting to neglect this part of your package, instead focusing only on your functional code, but good documentation means users can actually use your code.
You should write documentation for each function, each class, and each class method.
Users can access your documentation from within python using the help function.
This documentation explains the numpy-dot-sum function, and its parameters.
3. Why include documentation?
Similarly, this is the documentation for the numpy-dot-array class.
4. Why include documentation?
And this is the documentation for the dot-mean method of the array class.
5. Function documentation
Documentation is contained in a string at the top of each function. It begins and ends with three quotation marks.
6. Function documentation
The first sentence of documentation is a summary, and should read like a command; like you are telling the function what to do.
For simple functions this is all the documentation you will need.
7. Function documentation
For more complex functions you can add additional information below.
8. Function documentation
After the summary, you'll have sections outlining the input parameters, and returned values.
9. Documentation style
To write this section you will need to choose a documentation style.
There are several standard styles for python documentation you can choose, but you must be consistent within your package.
In this course you'll use the NumPy style. It's more verbose than the others, but it's good for documenting complex functions.
10. NumPy documentation style
It's also used in many scientific python packages, like NumPy, SciPy, Pandas, and Scikit-Learn.
11. NumPy documentation style
Let's look at the documentation of an example function.
The NumPy style uses section headings with underscores.
The parameters are laid out like this - the parameter's name, followed by a colon, and the parameter's type.
Here, array-like means a numpy array, a list, or a nested list, but in your own documentation you can specify any type.
Below this, on an indented line you should have a description of the parameter.
12. NumPy documentation style
If there are multiple options for the type of a parameter, or a certain set of valid values, you should list them all.
13. NumPy documentation style
The next section lists the returned values and their types in order. This is formatted just like the parameters list.
14. NumPy documentation style
These are the basic sections for any function. You can also include these other sections, which you can read more about here.
15. Documentation templates and style translation
Pyment is a tool used to generate template docstrings for your functions and classes. This is run from the terminal, and can generate documentation in many styles. It can also translate documentation from one of these styles to another.
16. Documentation templates and style translation
Here we use pyment to generate docstring templates for the textanalysis module you wrote earlier.
We use the w option to tell pyment to overwrite the textanalysis-dot-py file, and specify the output format as the NumPy style.
17. Documentation templates and style translation
pyment creates a template with headings and the parameter names. You'll need to fill in the rest of the detail.
18. Translate to Google style
Later, if you decide to change documentation style, you can use pyment again. We run the same command, but specify the Google docstyle. When pyment finds documentation which is not in this style it modifies it.
19. Translate to Google style
20. Package, subpackage and module documentation
There is also module, package, and subpackage documentation. This helps your users navigate your package and understand what it can do.
Package documentation is placed in a string at the top of the package init-dot-py file. This should summarize the package.
Similarly, subpackage documentation is placed at the top of the subpackage init-dot-py.
Module documentation is written at the top of the module file.
21. Let's practice!
We've covered a lot, now let's practice!