The KBUS documentation and sphinx¶
For your comfort and convenience, a pre-built version of the KBus documentation is available at:
or within the Mercurial
html repository at:
Building the documentation¶
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
You also need graphviz (which provides
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).
The Python bindings¶
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.
Mime type magic¶
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
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
hg checkout to retrieve them.
With luck the dependency tracking in the
make process will cope.