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