[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