[augeas-devel] User documentation for lenses

[Raphaël Pinson]

2011/11/30 David Lutterkort <lutter at redhat.com>:
> 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.


That's a good idea indeed. We'd then have to integrate them with ND,
which is doable (there's tags to integrate images with ND).


> 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.

I'm just matching everything. Not sure if ND can do it otherwise.

I've contacted the ND developer about newlines being removed when it
gets parsed, and it seems like it happens quite deep in the ND code,
so you have to override internal functions to get rid of that
behaviour.


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

Yes, just like lenses. You need to actually put comments (at least the
View: Reprepro_Uploaders.entry part) in order for ND to grab the code.


Raphaël