For your comfort and convenience, a pre-built version of the KBus documentation is available at:
or within the Mercurial html repository at:
The KBus documentation is built using Sphinx.
The documentation needs (at least) version 0.6 of Sphinx. Recent versions of Ubuntu provide this in the python-sphinx package; on older versions you should use easy_install as described on the Sphinx website.
You also need graphviz (which provides dot).
With luck, the HTML in the web repository will be up-to-date, and you won’t need to (re)build the documentation. However, if you should need to (for instance, because you’ve updated it), just use the Makefile:
Note that the html repository includes default as a subrepository; this means that if you’ve made changes to the doc source anywhere else, you have to update the subrepository before you build in html, probably with a line like this:
hg -R kbus pull <repo> hg -R kbus update
KBUS developers can push rebuilt docs back to Mercurial in the usual way; beware that the inheritance graphic is rebuilt every time and require hg add (and, ideally, the old ones removed).
Read the kbus-python-*.txt files to see how individual classes and functions within kbus.py are documented. Obviously, if you add, remove or rename such, you may need to alter these files – please do so appropriately.
Sphinx believes that the contents of docs are transitory - i.e., that it is free to delete them if it wishes. In particular, make clean will delete all of the contents of docs.
Meanwhile, we’ve committed docs/html and its contents to Mercurial.
This used to be a problem under Subversion, but is no longer since moving to Mercurial. If you accidentally make clean the docs away, you can use hg checkout to retrieve them. With luck the dependency tracking in the make process will cope.