patch to improve documentation for samba-tool command --help
jelmer at samba.org
Mon Oct 17 10:26:51 MDT 2011
-----BEGIN PGP SIGNED MESSAGE-----
On 10/17/2011 05:44 PM, Theresa Halloran wrote:
> Hi all,
> 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.
> I also changed the samba-tool user add to samba-tool user create. I
think create is more accurate than add since the user is being created
with this command, as opposed to added, which is used for e.g. when we
add a user to a group...in the add case the user already exists.
Thanks for working on this. I didn't realize there was a way to get
optparse to stop stripping newlines from help texts.
It might make sense to split up these changes ("net user add -> net user
create" and the help improvements), so they can be discussed and landed
separately (and one doesn't have to block on the other).
The renaming of "net user add" to "net user create" seems reasonable to me.
> 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.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
-----END PGP SIGNATURE-----
More information about the samba-technical