Fwd: Re: patch to improve documentation for samba-tool command --help
thallora at linux.vnet.ibm.com
Mon Oct 24 05:51:59 MDT 2011
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)....
-------- 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
Attached is the patch. Thanks, as always, comments are appreciated!
>>> 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...
More information about the samba-technical