On 08/19/2011 03:52 PM, Russell Bryant wrote:
- 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.
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/1536784ef210883709dafad8eb755ea3...
Thoughts?