OpenLMI documentation suite

Russell Doty rdoty at redhat.com
Tue Oct 1 17:37:04 UTC 2013


Excellent work!

I was looking at the Account Provider, specifically page
http://jsafrane.fedorapeople.org/openlmi-storage/scratch/doc/admin/all/clones/openlmi-providers/src/account/doc/source/usage.html#list-users

In the example there is extensive us of name/value pairs. I can't find
where the available names and allowed values are documented; can you
point me to this?

Thanks,
Russ

On Tue, 2013-10-01 at 09:34 +0200, 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.
> 
> 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
> _______________________________________________
> openlmi-devel mailing list
> openlmi-devel at lists.fedorahosted.org
> https://lists.fedorahosted.org/mailman/listinfo/openlmi-devel




More information about the openlmi-devel mailing list