OpenLMI documentation suite

Jan Safranek jsafrane at redhat.com
Tue Oct 1 07:34:27 UTC 2013


Currently we have our documentation spread across various git
repositories, which is fine, because we have documentation tightly
connected to actual implementation. On the other hand, the generated
documentation is spread across various fedorapeople sites and it's quite
hard to find.

I've been playing with Sphinx to generate overall documentation from all
OpenLMI git repositories into one nice HTML site. Also, I've created a
Sphinx template to make it a bit nicer.

See http://jsafrane.fedorapeople.org/openlmi-storage/scratch/doc/

It has following structure

doc
|
+- admin
|  +- latest <latest storage+networking+providers combined together>
|  +- storage
|  |  +- 0.5.2
|  |  +- 0.5.3
|  |  +- 0.6.0
|  |  + ...
|  |
|  +- networking
|  |  +- 0.1.0
|  |  +- 0.2.0
|  |  + ...
|  |
|  +- providers
|     +- 0.1.0
|     +- 0.2.0
|     + ...
|
+- client?
   +- latest <latest scripton + lmi command docs>
   +- 0.0.1
   +- 0.0.2

Especially note overall documentation of the latest storage + networking
+ providers combined together at
http://jsafrane.fedorapeople.org/openlmi-storage/scratch/doc/admin/latest/

I don't have the 'client' part yet, I just assume it will be similar to
the provider documentation.

I would appreciate any comments to directory structure, css style or the
actual text content. The documentation (in proposed directory structure)
will end up on openlmi.org eventually.

It is surprisingly complex process to generate such documentation,
partly because different providers use different documentation build
process (cmake vs make) and the documentation sources are in different
git repositories on different places.

Therefore I've created:
- OpenLMI Sphinx theme package, which *must* be installed when
generating the docs, so we don't need to copy the theme to all our git
repos. It's subpackage of openlmi-providers.srpm.
- openlmi-providers/tools/gendoc tool, which builds the documentation in
mock from fresh git clones. Mock is used to install various weird tools
like dia and plantuml there + we have reproducible and untainted doc build.

I'll send appropriate patches to review, if this style looks ok to you.

Jan


More information about the openlmi-devel mailing list