Blueprint-clients-man-pages
- Launchpad Entry: clients-man-pages
- Created: 23 May 2013
- Contributors: Jakub Ruzicka
Contents
Summary
Provide helpful and maintainable man pages to all OpenStack command line clients.
Rationale
Currently, OpenStack clients (python-novaclient, python-glanceclient, ...) provide command line scripts without man pages. Good man page can make user's life easier and providing them is definitely a good practice.
Generated vs Manual
Although it is possible to generate man pages from code the same way the help is generated (possibly with adding verbose descriptions to command functions) in order to avoid manual syncing with code, this isn't likely to result in a good man page. Quoting Sean Dague:
- 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.
Content
Man page should contain at least:
- summary about what is the tool used for
- basic usage
- how to get available commands and options (`$CLIENT help`)
- how to get command help (`$CLIENT help <command>`)
- examples of common tasks
Ideally, man page should also contain:
- verbose descriptions/clarifications of commands and options
- tips & caveats
- links to related docs
- any other useful information
Implementation - reStructuredText (rst)
As man page format isn't very readable or maintainable, more appropriate format should be used.
Why rst:
- OpenStack components use it for docs and man pages already
- both docs and man pages can be generated using sphinx
- easy to read and maintain
- well known and python friendly
Refer to components with manpages (Nova, Glance, Quantum, ...) for implementation details.
