Open Stack

I concur.

In this scenario, question is what to start with. I'm not able to write
verbose descriptions for all the commands and options of all clients
with overarching narrative as I don't have much experience with them.
Not to mention time.

I'd like to start with *something* slightly useful on its own which
others can expand.


Jakub

On 22.5.2013 13:46, Sean Dague wrote:
> My experience is that you never get a good result trying to create man
> pages out of comments embedded in the code.
> 
> The reason is pretty simple: the comments in the code are very narrow,
> and don't put that in the context of other options.
> 
> But a good man page needs so overarching narrative, and relationship
> between options. When you see the content all together in one place, and
> are editing it in one place, you can see the level of disjointness. When
> someone is just adding content to their individual options this context
> doesn't exist.
> 
> I'd suggest doing rst in doc/source like is being done with other
> projects. The sphinx rules can build man format easily enough.
> 
>     -Sean
> 
> On 05/21/2013 03:23 PM, 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
>>
>>
>> On Tue, May 21, 2013 at 2:00 PM, Anne Gentle <anne at openstack.org
>> <mailto: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
>>     <mailto: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
>>         <mailto: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
>>     <mailto: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
>>
> 
>