[openstack-dev] [opinion-wanted] Clients man pages
Jakub Ruzicka
jruzicka at redhat.com
Wed May 22 11:46:02 UTC 2013
That sounds pretty good and maintainable. verbose_description kwarg for
options makes sense, but what about verbose description of the command?
Currently a docstring is used as description:
@utils.arg('--option', metavar='<SOME_ID>', help='This option does something.')
def do_something(gc, args):
"""Description displayed by help."""
<code>
What about something like this?
@utils.arg('--option', metavar='<SOME_ID>', help='This option does something.',
long_description=("This option is useful when you want to "
"do something but something else. Also, when "
"foo then bar and what not."))
@utils.long_description("""
This commands does various things, like you'd expect. It can work like banana
or an orange depending on your fruits configuration.
When something_different is set, this command is even more awesome and apple
behaviour is applied.
""")
def do_something(gc, args):
"""Description displayed by help."""
<code>
This brings few questions:
* Howto write these long strings (" vs """)?
* When talking about multiple formats, should descriptions have words wrapped?
* Should this be plaintext or rST?
Thanks
Jakub
On 21.5.2013 21:23, Dolph Mathews wrote:
> I'd like to see more details provided through oslo.config (perhaps an
> verbose_description kwarg for each option, or something similar?), so that
> we can render that additional documentation to multiple formats (man pages,
> openstack manuals, etc) beyond CLI --help.
>
>
> -Dolph
More information about the OpenStack-dev
mailing list