If we want our package to be used by others, or simply wish to go back to our code after a few days, we really need to have some reasonable documentation.
Python encourages the use of in-situ documentation in the form of docstrings. Docstrings are simply standalone strings after the definition of functions/classes/etc.:
In [ ]:
def add(a, b):
"""This is my addition function which adds two numbers together."""
return a + b
Python's built-in help function can then be used to display the help:
In [ ]:
help(add)
Similarly, IPython can also be used to view docstrings:
In [ ]:
add?
Writing good documentation takes practice and time, but done well it can speed up development and make your code more maintainable.
numpydoc is a set of recommendations on how to write and layout your docstrings such that they are consistent and easily understandable to fellow scientific Python users. Our add function's docstring, when following the numpydoc guidelines, might looks something like:
In [ ]:
def add(a, b):
"""
Add two values together.
Parameters
----------
a : object
The left hand of the addition.
b : object
The right hand of the addition.
Returns
-------
result : object
The result of doing ``a + b``.
Examples
--------
>>> add(0.5, 1.5)
2.0
"""
return a + b
Sphinx is a Python package to generate web pages (as well as PDF & more) for your documentation. Python's own documentation is generated with sphinx, with the docstrings of functions/classes/etc. extracted directly from the source to avoid duplicating the information.
We can create basic sphinx documentation very quickly with the sphinx-quickstart command line tool.
Let's do that by going to tutorial_classroom and making the root directory "docs":
cd tutorial_classroom
sphinx-quickstart docs
To create the documentation, let's run make html from within the docs:
In [ ]:
%cd tutorial_classroom
%cd docs
In [ ]:
!make html
!open build/html/index.html
Notice how a config file has been created in source/conf.py:
In [ ]:
%ls source
This config file is were details about our project are stored - things like project name, version, author etc. as well as information about the layout and style of the documentation itself.
Let's update the theme of the documentation by changing the config file's html_theme value from default to sphinxdoc, and re-build the documentation to see the effect.
You will notice that currently we do not have any documentation for the functions in classroom in our built docs. This is because sphinx has been designed for a semi-manual documentation approach. To automatically pull in the documentation for our classroom module, we should enable the 'sphinx.ext.autodoc' extension in the conf.py configuration, and add
.. automodule:: classroom
:members:
:undoc-members:
To the restructured text in index.rst. This tells sphinx to pull in all of the documentation from the classroom module, including functions which do not have docstrings defined. More information about the automodule (and other auto* directives) is available on the sphinx documentation.
Let's create a new euroscipy_2014.rst file with for this tutorial, and link to it from the TOC (table of contents) of index.rst.
Exercise:
We have previously created the euroscipy_2014.rst file by hand, now that we have our interface to access the classroom data, programmatically generate the rst file and put it in the documentation source.
A full repository of the classroom package, complete with tests and documentation, can be found in the full_package branch of https://github.com/pelson/tutorial_classroom.
In [1]:
%run resources/load_style.py