[Freeipa-devel] [PATCH] Add more sophisticated help interface. Split commands into 'topics'.

[Pavel Zuna]

Rob Crittenden wrote:
> Pavel Zuna wrote:
>> This is more of a suggestion than a real patch. I thought it might be 
>> easier to actually show what I had in mind than explaining it. 
>> Sometimes code is more than words. :)
>>
>> Pavel
> 
> I think this is a good start. The output looks like:
> 
> $ ipa
> Usage: ipa [global-options] COMMAND ...
> 
> Use `ipa help TOPIC` for command listings.
> 
> Topics:
>   general      General IPA management.
>   aci          ACI object.
>   application  Application object
>   automount    Automount object.
>   delegation   Delegation object.
>   group        group object.
>   host         Host object.
>   hostgroup    hostgroup object.
>   netgroup     netgroup object.
>   rolegroup    rolegroup object.
>   service      Service object.
>   taskgroup    taskgroup object.
>   user         User object.
> 
> Try `ipa --help` for a list of global options.
> 
> It looks like you dumped things that aren't related to a top-level class 
> into general (things like passwd, the cert commands, and a few others). 
> I guess they have to go somewhere, just not sure I'd know to look in 
> general if I was a new user.
> 
> Should we mandate an Object for every plugin? Or include the list of 
> these general commands in the main topics list? That might be confusing 
> too because that would mean that 'env' is on the same level as 'user'.
> 
> Any suggestions?
> 
> The patch is good and we could easily just apply this but I don't want 
> to forget about these issues. In any case we'll want to go into each 
> plugin and set the Object documentation to be more descriptive.
> 
> rob
I wrote another version of the help interface today taking into consideration 
the issues you mentioned. It's based on plugins this time instead of objects.

The output looks like this:

$ ipa
Usage: ipa [global-options] COMMAND ...

Built-in commands:
   console         Start the IPA interactive Python console.
   help            Display help for a command or topic.

Help topics:
   aci             Frontend plugins for managing DS ACIs
   application     Frontend plugins for application policy containers.
   automount       Frontend plugins for automount.
   defaultoptions  Frontend plugin for default options in IPA.
   delegation      Frontend plugins for delegations.
   dns             Frontend plugin for DNS management.
   group           Frontend plugins for groups.
   hbac            Frontend plugin for HBAC management.
   host            Frontend plugins for host/machine Identity.
   hostgroup       Frontend plugins for hostgroups.
   join            Machine join
   misc            Misc frontend plugins.
   netgroup        Frontend plugins for netgroups.
   passwd          Frontend plugins for password changes.
   pwpolicy        Frontend plugins for password policy.
   rolegroup       Frontend plugins for rolegroups.
   service         Frontend plugins for service (Identity).
   taskgroup       Frontend plugins for taskgroups.
   user            Frontend plugins for user (Identity).

Try `ipa --help` for a list of global options.

Commands not originating from plugins are listed as built-ins. The short 
description for topics is taken from the first line of the module's docstring.

The code itself is a bit hacky, because I just couldn't find any better way to 
get every plugin module, it's docstring a list of commands it implements. I'll 
rewrite it if necessary.

Pavel
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: 0001-Change-help-interface-to-display-builtin-commands-an.patch
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20090416/00703144/attachment.ksh>