[dev] The library section of the Horde website supports component documentation now.

[p at rdus.de]

Our new libraries[1] section has been started a while ago to further push
the PHP components we offer. Now this section supports publishing the
component documentation as well. You can take a look at the documentation
of the Cli_Modular[2] package for example. In fact: it is pretty much the
only package that fully uses the new system already. So there is still work
ahead.

IF YOU USE ANY OF THE COMPONENTS: WE ARE GRATEFUL IF YOU START WRITING A
BIT OF DOCUMENATION OR DESCRIBE SOME EXAMPLES ON HOW TO SUCCESSFULLY USE
THE PACKAGE. IT WILL HELP US AND OTHERS TREMENDOUSLY. THANKS!

Let me try to explain how the system is currently intended to work -
feedback and critical comments of course welcome:

   * When creating new documentation for one of the Horde components you
start a new section on the developer documentation of our wiki[3]. See the
Horde_Cli_Modular[4] link below LIBRARY COMPONENTS for example. Please
note: It is not mandatory to write the documentation in the wiki. You can
have static documentation files within a component as well. This is just
meant as an option for those situations where it makes sense to work on
documentation files together with people that do not have direct git commit
access. Hopefully there will be many component consumers interested in
updating and fixing the documentation.
   * How you structure that new section is up to you. For a simple package
you might wish to keep all documentation in a single file but for the more
complex one it might make sense to have several files. In that case the new
section page should probably just be a link list to the various wiki pages
that document the component. In case of Horde_Cli_Modular[4] I used a
single page.
   * Once the documentation has been written in the wiki format it is time
to download it into the doc directory of the component. The
horde-components[5] helper is what you should use for that operation. The
tool expects to find a DOCS_ORIGIN[6] file within the doc or docs (for the
applications) directory of the component. This file must conform to the
reStructuredText[7] format and map remote URLs to local file paths relative
to the component root. The DOCS_ORIGIN from Cli_Modular[6] links the wiki
page[4] exported as reStructuredText[7] to the path
doc/Horde/Cli/Modular/README[8]. The links can of course point anywhere so
you are in principle free to use any remote source. But you should ensure
the page provides readable reStructuredText[7].
   * Now you can run horde-components fetchdocs and it should fetch the URLs
into the respective local files. You can then run horde-components update
to refresh the file list in the package.xml file if the documentation files
were not included before.
   * Once a component was released we can now run something like this:
horde-components Horde_Cli_Modular webdocs -D ~/git/horde-web/
--html-generator=git/horde-support/maintainer-tools/docutils/html.py
--allow-remote in order to update the documentation on the website[2].
Right now this does not happen automatically during a release but I plan to
add this soon.

There are of course still a few problems with this approach:

   * The reStructuredText[7] exporter of our wiki engine "Wicked"[9] is not
yet complete. You may experience problems with the export if you use
constructs it does not know yet. Please ping me if you experience problems
with the export.
   * The wiki syntax and the syntax required by reStructuredText[7] is not
100% aligned. You can write a wiki page that looks just fine but leads to
errors or formatting problems in the reStructuredText[7] export. After
creating / updating a new wiki documentation page it make sense to run the
horde-components fetchdocs/horde-components webdocs sequence to check for
problems.
   * We still have some components with documentation files not in
reStructuredText[7] format. These will result in non-existing links on our
website for now but I plan to fix the few faulty packages soon.



Links:
------
[1] http://www.horde.org/libraries
[2] http://www.horde.org/libraries/Horde_Cli_Modular/docs
[3] http://wiki.horde.org/Doc/Dev
[4] http://wiki.horde.org/Doc/Dev/HordeCliModular
[5] http://wiki.horde.org/Doc/Dev/Component/Components
[6]  
https://github.com/horde/horde/blob/master/framework/Cli_Modular/doc/Horde/Cli/Modular/DOCS_ORIGIN
[7] http://docutils.sourceforge.net/rst.html
[8]  
https://github.com/horde/horde/blob/master/framework/Cli_Modular/doc/Horde/Cli/Modular/README
[9] http://www.horde.org/apps/wicked