patch to improve documentation for samba-tool command --help
jelmer at samba.org
Tue Oct 25 02:41:50 MDT 2011
On Wed, 2011-10-19 at 14:05 -0400, Theresa Halloran wrote:
> 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!
Sorry for taking so long to get back to you. I think this looks good.
In general, we stick to 80 characters per line, consistent with PEP8
(www.python.org/dev/peps/pep-0008), but I guess in this case that would
break the paragraphs? That can perhaps be improved in a later patch.
I'm not a native English speaker, so perhaps somebody who is can also
have a look at the proposed help text.
> +This command creates a new user account in the Active Directory
domain. The username specified on the command is the SAMaccountname.
Should this perhaps be "specified on the command-line" ?
> +User accounts may represent physical entities, such as people or may
be used as service accounts for applications. User accounts are also
referred to as security principals and are assigned a security
"may be used for application service accounts" sounds better to me.
> +A user account enables a user to logon to a computer and domain with
an identity that can be authenticate. To maximize security, each user
should have their own unique user account and password. A user's access
to domain resources is based on permissions assigned to the user
I think "user's" should be "users'"
> >>> 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 --------------
A non-text attachment was scrubbed...
Size: 836 bytes
Desc: This is a digitally signed message part
More information about the samba-technical