OpenLMI documentation suite

Jan Safranek jsafrane at redhat.com
Wed Oct 2 10:03:58 UTC 2013


I uploaded preview of today's git master documentation with fixes
mentioned in this thread to:
http://jsafrane.fedorapeople.org/openlmi-storage/scratch/doc/

Jan

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