[Freeipa-devel] [PATCH] Change help interface to display builtin commands and a list of topics based on plugins.

[Pavel Zuna]

Rob Crittenden wrote:
> 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
There, I also made some small changes to the code and added a few comments to 
make it a little more readable.

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/20090420/dc843ec0/attachment.ksh>