Open Stack

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
>


-- 
Sean Dague
http://dague.net