OpenLMI documentation suite

Jan Synacek jsynacek at redhat.com
Tue Oct 1 07:54:34 UTC 2013


On 10/01/2013 09:51 AM, Jan Synacek wrote:
> 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
> 

Oh, and one more thing. Let's get rid of the 'Indices and tables' section
everywhere. I don't think it serves any purpose and it just makes the contents ugly.

-- 
Jan Synacek
Software Engineer, Red Hat


More information about the openlmi-devel mailing list