As tests document the API why not to treat them as a part of the documentation? Thankfully this is quite simple to do in practice using doctests. As I converted my unit tests to doctests I managed to simplify the API even.
After getting rid of the unit test I came up with the following project layout (final version):
- /pynu - Project root
- /pynu/[CHANGELOG, INSTALL, README, setup.cfg, setup.py, TODO] - Misc. project files
- /pynu/docs - Documentation root
- /pynu/docs/[conf.py, index.rst, make.bat, Makefile] - Misc. documentation files
- /pynu/pynu - Package root
- /pynu/pynu/__init__.py - Package identifier
- /pynu/pynu/graph.py - GraphNode
- /pynu/pynu/node.py - Node utilities (base class etc.)
- /pynu/pynu/tree.py - TreeNode
Generating the Documentation
In this case I decided to use Sphinx for my documentation purposes. Sphinx provides you a semi-automatic way to build your documentation. You can structure the documentation the way you want and fetch the docstring documentation on demand using autodoc extension.
You can find more information about it at the official documentation. See also this post and this tutorial.
After installing Sphinx ("easy_install sphinx") it's possible to generate initial starting point for documentation. This can be done simply by running "sphinx-quickstart" at your project root (ie. /pynu in this case). It will ask you a series of questions. If you want to store your documentation in /docs the way I did, provide path "./docs" as an answer to the first question. The defaults it provides are mostly just fine (hit return to accept the default). If you forgot to enable "autodoc", this can be fixed at configuration (/docs/conf.py). In this case it needs a couple of extra changes anyway. I ended up doing following changes to my conf.py:
Besides configuration, actual markup for documentation is needed. I came up with following (note autodoc notation):
Packaging and Publishing at PyPI
In order to publish the package at PyPI (Python Package Index) I had to register to PyPI, implement setup.py and do some command line magic. The whole process has been described well here so I won't elaborate on that any further.
In this tutorial I showed how to set up autodoc based documentation for a project. In the next post I will look into packaging and expanding the file system module written for Placidity.