On Tue, Aug 23, 2011 at 6:41 AM, Russell Bryant <rbryant(a)redhat.com> wrote:
On 08/19/2011 03:52 PM, Russell Bryant wrote:
> 2) Use the existing docbook manual (dev-manual in links above) as the
> base for the documentation. Move the existing content to be a "Writing
> a new agent" chapter.
>
> 3) Create two new chapters:
>
> - Chapter 1: Project Overview
> Go over the project from a user's point of view. List the
> agents that we have and at a high level, what they provide.
>
> - Matahari APIs
> The APIs we provide. The core of this chapter can be
> automatically generated using an XSLT similar to doc/api.xsl.
> Instead of transforming into a plain text format, it could
> generate docbook XML.
>
> Publican does a great job of rendering stellar looking documentation
> from docbook. If we complete these steps, I think we'll have a great
> manual that addresses our entire audience.
Here is a first pass on implementing what I described above.
http://www.russellbryant.net/matahari/en-US/html/
The Matahari APIs chapter is auto-generated. I haven't added the
overview chapter that I described above, yet. This will get better if
more and more documentation gets added to the schema files.
I probably need to go back and reconsider the details of some of the
docbook markup. The <section> depth gets kind of out of hand. However,
what's there gets the concept across.
The implementation can be found here:
https://github.com/russellb/matahari/commit/1536784ef210883709dafad8eb755...
Thoughts?
I like it. Much better than my xslt conversion to text.