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

[Pavel Zuna]

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