[augeas-devel] User documentation for lenses

[David Lutterkort]

On Wed, 2011-11-30 at 08:34 +0100, Raphaël Pinson wrote:
> Hello,
> 
> 
> I've always wanted to improve user documentation for lenses. I think
> most users get lost trying to guess the paths to use in Augeas. This
> is already the reason why I had introduced NaturalDocs documentation 3
> years ago.
> 
> Now I'd really like to improve it a bit more. In the last lens I've
> been working on (reprepro_uploaders.aug), I've tried to add useful
> comments, and I've activated NaturalDocs comments for tests. The
> result can be seen on
> http://r.pinson.free.fr/augeas/doc/lenses/files/reprepro_uploaders-aug.html
> and http://r.pinson.free.fr/augeas/doc/lenses/files/tests/test_reprepro_uploaders-aug.html.

Wow. This is awesome. BTW I prefer option (4) We could also generate
graphical trees - it wouldn't be too hard to hack up augparse to
generate .dot files.

Also, I'd find the test part clearer if the green box did not contain
the tree and we showed that only underneath the box.

Do we need to annotate all tests or can NaturalDocs just produce a page
for each test_ file ?

David