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

[David O'Brien]

Pavel Zuna wrote:
> 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
> ------------------------------------------------------------------------
>
> _______________________________________________
> Freeipa-devel mailing list
> Freeipa-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/freeipa-devel
How much work is involved in editing the first line of a module's 
docstring? Is it developer-only territory or straight-forward enough 
that I could do it?

I ask because I'm interested in keeping everything related to doc, help, 
etc., on an even keel and consistent, which in this case means:
s/plugin/plug-in
s/backend/back-end
s/frontend/front-end

I would also review the use of terms like "host/machine", because in IPA 
2.0 "host" refers to the host object specifically created to represent 
the host *machine*, and which exists as a new object in DS. "Machine", 
on the other hand, refers to the computer itself. (This gets trickier 
when we start talking about the "host" where a virtual machine is 
running.) Hopefully my understanding of host objects and machines is 
correct here.

So, in the case of "host : Frontend plugins for host/machine Identity." 
I'd suggest a change to "host : Front-end plug-ins for machine identity."

1. front-end (as per style guide)
2. plug-ins (as per style guide)
3. machine (we're identifying the machine, and using the host object to 
do it)
4. identity (lower case)

regards,

-- 

David O'Brien
IPA Content Author
Red Hat Asia Pacific
+61 7 3514 8189

"The most valuable of all talents is that of never using two words when
one will do."
    Thomas Jefferson