Fwd: Re: patch to improve documentation for samba-tool command --help

[Theresa Halloran]

Hi Jelmer and all,

Could you review the patch attached for updates to the --help?  I'd like 
to start submitting patches with the actual doc text for improving 
--help on samba-tool commands, but would like to be sure my approach for 
adding the doc to the code is accepted.

In the patch below, I'm using __doc__ for the text of the help (the code 
to handle was previously added).  I added a formatter subroutine that 
preserves newlines in the doc since now some of the writeups are more 
substantial and I'll need more than one paragraph.

I've also included the text for --help for samba-tool user create to see 
if people think the scope of the information presented is ok (i.e. too 
little, too much, more examples)....


Thanks,
Theresa

-------- Original Message --------
Subject: 	Re: patch to improve documentation for samba-tool command --help
Date: 	Wed, 19 Oct 2011 14:05:57 -0400
From: 	Theresa Halloran <thallora at linux.vnet.ibm.com>
To: 	samba-technical at lists.samba.org



Hello Jelmer and all,

I am using full_description for the enhanced --help information and
updated user.py to add the text to the __doc__ section.  I added the
formatter code so the newlines are preserved.  This will work well for
the enhanced help.  I don't see the full_description being used for
anything else...unless there is a plan to do so and a reason I should
not use it (or if I missed something).

I've included the text I'll be adding for samba-tool user create.
Please review the text for accuracy and completeness (which I realize is
subjective)....

Attached is the patch.  Thanks, as always, comments are appreciated!

Theresa
>>>
>>>  I've attached a patch with an implementation to improve the --help
>>  command for samba-tool. It includes some formatting stuff and an example
>>  of the samba-tool user create --help doc that gives an idea of the level
>>  of detail and some command examples.
>>  Thanks for working on this. I didn't realize there was a way to get
>>  optparse to stop stripping newlines from help texts.
>>>  Input is appreciated. Once an approach is decided upon, I'll be
>>  updating the --help for the rest of the samba-tool commands.
>>
>>  The base Command class in samba.netcmd already supports a
>>  "long_description" field, which is intended to contain the same contents
>>  your patch now puts into 'full_description'. It bases its contents on
>>  the contents of the docstring, and dedents it, so that you can simply
>>  write that as you normally would, and there's no need to add extra
>>  newlines and the like.
>>
>>  I'm not sure if long_description is used anywhere with multiple
>>  paragraphs yet (there hasn't been a point in doing that, as the help
>>  formatter would just discard the newlines), but we should fix that up if
>>  it doesn't work.
>  Ok, originally I had coded long_description, but then I saw
>  full_description (which I think is relatively new?) on the
>  description field (description=self.full_description), prior to my
>  update... I changed it to use full_description...what is
>  full_description used for?
>  anyway, I'll look into it.




-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: 0001-s4-samba-tool-help-enhancement.patch
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20111024/d1e29f2e/attachment.ksh>