Open Stack

On 22.5.2013 13:32, Thierry Carrez wrote:
> Jakub Ruzicka wrote:
> 
>> GENERATED VS MANUAL
>> ===================
>>
>> Although man pages can be generated the same way as help, a copy of help
>> output doesn't bring any real value.
>>
>> Man page should provide something extra like:
>>  * verbose descriptions of more complicated commands/options
>>  * howto use the tool to solve common tasks
>>  * examples of usage
>>  * where to find more information
>>
>> Do you see any value in including the command list in man page without
>> providing more detailed information than `$CLIENT help` does?
> 
> There is value in keeping the man page details together with the code
> though, as it's easier to keep the two in sync. I agree that the "help"
> output is not appropriate, but maybe there is still a way to generate
> man page content from data that is stored in the code together with
> options ?

Although that is certainly possible (I.E. additional utils.arg kwarg for
options and new decorator for command verbose description), question is
if this will result in a good manpage. See Sean's mail up the thread on
this topic.

It is also possible to insert this generated info into a section of man
page while maintaining the rest manually. That way, command specific
information wouldn't fall out of sync on changes as dev would see it
where he modifies the code.

For example with optional decorator:

@utils.command_info("""
Something you should definitely know about this awesome command.

Something something something Dark Side. Something something complete.
""")
do_something(gc, args):
    <code>

Commands decorated with it might be generated into appropriate manpage
section.


Jakub