OpenLMI documentation suite

Jan Synacek jsynacek at redhat.com
Tue Oct 1 07:51:04 UTC 2013


On 10/01/2013 09:34 AM, Jan Safranek wrote:
> 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.

Nice! The CSS looks very well in my opinion. The directory structure looks ok as
well. I would add 'latest' directory to every subdirectory that would always
point to the latest version of the docs -- something like a symlink, so you
could refer to 'latest' in the link, for example. And maybe I would rename the
current top-level 'latest' to something like 'all' ?

> 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.

Let's unite that. For example, since we already use cmake extensively, let's use
that.

> 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

-- 
Jan Synacek
Software Engineer, Red Hat


More information about the openlmi-devel mailing list