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

[Rob Crittenden]

Pavel Zuna wrote:
> David O'Brien wrote:
>> 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,
>>
> Docstrings are a feature of python for associating documentation with 
> objects like modules, classes, function, etc. in the code. They are 
> meant for developers, but are easy to spot and edit. They are always 
> surrounded with 3 double quotes on both sides, like this:
> 
> """docstring - this is the first line containing text, short help"""
> 
> """
> docstring - this is the first line containing text, short help
> 
> blablabla
> """
> 
> Module docstrings are always located at the top of the file before any 
> code, usually just after the authors/license comments (staring with #).
> 
> Command docstrings can be found at the beginning of it's class 
> definition. For example, if we have a command named Foo in plugin module 
> Bar:
> 
> (contents of ipalib/plugins/Bar.py)
> ...
> 
> class Foo(Command):
>     """
>     docstring - first line, short description of what the command does
> 
>     more information displayed on `ipa help Foo`
>     """
> 
> ...
> 
> The current text in module's docstrings were not meant to be displayed 
> as help for topics. If we're going to use this help scheme, they'll have 
> to be rewritten.
> 
> For topics, I think the first line should say what the topic is, so the 
> output look something like this:
> 
> Topics:
>   aci     Directory Server Access Control Instructions
>   hbac    Host-Based Access Control
>   ...
> 
> Additional lines should offer more in depth information, possibly with 
> links to online docs.
> 
> Pavel

Pavel, can you update the topic descriptions along with this patch. Then 
I'll ack both. I think we're going to have to get this in place and use 
it a while to see what fine-tuning it needs. I think this is the right 
approach though.

rob