[augeas-devel] User documentation for lenses

[Raphaël Pinson]

2011/11/30 Raphaël Pinson <raphink at gmail.com>:
> 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).
>

Here is a manual mockup of a dot file (and generated PNG):


graph "and_or" {
   label="allow sections 'main'|'restricted' and source 'bash' or
binaries contain 'bash-doc' by anybody"

   allow -- and1;
   and1 [label="\"and\""]
   and1 -- and1_or1;
   and1_or1 [label="\"or\" = \"sections\""];
   and1_or1 -- and1_or1_1;
   and1_or1_1 [label="\"or\" = \"main\""];
   and1_or1 -- and1_or1_2;
   and1_or1_2 [label="\"or\" = \"restricted\""];

   allow -- and2;
   and2 [label="\"and\""]
   and2 -- and2_or1;
   and2_or1 [label="\"or\" = \"source\""];
   and2_or1 -- and2_or1_1;
   and2_or1_1 [label="\"or\" = \"bash\""];
   and2 -- and2_or2;
   and2_or2 [label="\"or\" = \"binaries\""];
   and2_or2 -- and2_or2_contain;
   and2_or2_contain [label="\"contain\""];
   and2_or2 -- and2_or2_1;
   and2_or2_1 [label="\"or\" = \"bash-doc\""];
}

The result is: http://i.imgur.com/ovoY0.png


I don't know augparse enough to know if it could generate this easily,
but it's probably the tool that understands test files the best
currently.


Raphaël