The KBUS documentation and sphinx¶
Pre-built documentation¶
For your comfort and convenience, a pre-built version of the KBus documentation is available at:
or within the Mercurial html
repository at:
html/docs/html/index.html
Building the documentation¶
The KBus documentation is built using Sphinx.
Note
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:
make html
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¶
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.
Mime type magic¶
In order for the documentation in the Google Code Mercurial repository to be useable as documentation, the HTML, CSS and JavaScript files in the docs/html directory tree need to have the correct mime types. Mercurial is clever enough to be able to cope with this, though Subversion needed extra help.
Mercurial gotchas¶
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.