Open Stack

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


On Tue, May 21, 2013 at 2:00 PM, Anne Gentle <anne at openstack.org> wrote:

> Hi Jakub,
> Thoughts below, thanks for sending.
>
>
> On Tue, May 21, 2013 at 1:52 PM, Jakub Ruzicka <jruzicka at redhat.com>wrote:
>
>> Hello,
>>
>> I plan to provide consistent man pages for all OpenStack clients and I'd
>> love to see your opinion about few important details:
>>
>>
>> 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?
>>
>> Sure. More info is good as long as it is accurate (so maintained, that's
> the tough part as you allude to).
>
>>
>> FORMAT
>> ======
>>
>> man format is ugly and hard to maintain, man page should be stored in
>> something saner like reStructuredText or AsciiDoc.
>>
>> Which format do you recommend?
>>
>>
> I made an attempt a few releases ago to get nova man pages done in RST.
> See https://github.com/openstack/nova/tree/master/doc/source/man. Swift
> did the same at
> https://github.com/openstack/swift/tree/master/doc/manpages. You could
> use those to see how rst could work for the clients. However I don't
> believe these are accurate since they're not well-maintained. So the format
> doesn't necessarily help with maintenance.
>
>
>
>>
>> CONTENTS
>> ========
>>
>> I'd like to include few useful examples of most common use cases for sure.
>>
>> Beyond that, there are basically 3 options:
>>
>> 1) Provide only basic information with bold
>> """
>> Run `$CLIENT help` to get available commands and their descriptions.
>>
>> Run `$CLIENT help <command>` to get information about <command>.
>> """
>>
>> 2) Provide detailed information about selected commands/features/tasks
>> only.
>>
>> 3) Provide detailed information about all commands. As I don't have so
>> much time on my hands, I'd start with `$CLIENT help` (pretty much what
>> help2man outputs) and extend it over time with detailed information.
>> I don't like this very much because:
>>  * Will someone actually extend it?
>>  * This would require maintenance and could easily go out of sync.
>>
>> What should be in the man page?
>>
>>
>> BLUEPRINT
>> =========
>>
>> What is the best way to create a blueprint concerning multiple
>> components (all the clients) in LP?
>>
>>
>>
> You could log a blueprint for openstack-manuals at
> http://blueprints.launchpad.net/openstack-manuals since it's a common doc
> consistency task. Not sure the doc team has resources to spare this release
> as we have some blueprints that came up prior to the Summit, but I'm happy
> to facilitate as needed.
> Thanks,
> Anne
>
>
>>
>> Thanks in advance for your valuable input!
>>
>> Jakub Ruzicka
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130521/b54eba7c/attachment.html>