patch to improve documentation for samba-tool command --help
thallora at linux.vnet.ibm.com
Wed Oct 19 12:05:57 MDT 2011
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