Pynu - 0.1.0 released + Documentation tutorial

I just released the first version of Pynu, my node utility library for Python. It was developed based on the node module of Placidity. I converted the unit tests to doctest form and derived documentation directly based on that. In this post I will recap the steps I took and focus especially on the documentation part.

Project Structure

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
  

Note that in this case I made conscious decision not to put documentation inside the package itself. In this case I prefer to build the package so that it does not contain any specific documentation and provide the it separately. Thanks to docstrings it's possible to introspect most of the documentation via Python so in most cases you probably don't need to refer to actual documentation anyway.

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):

index.rst:


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.

Summary

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.