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 _______________________________________________ openlmi-devel mailing list [email protected] https://lists.fedorahosted.org/mailman/listinfo/openlmi-devel
