format command line app documentation using sphinx features

[Doug Hellmann]

Sphinx provides directives and roles for describing command line programs. We should use them for nova-manage.

http://sphinx.pocoo.org/domains.html?highlight=program#directive-program

[Romain Chantereau (romain-m)]

This syntax does not permit option without “-”, “--“ or “/” prefix when using sphinx 1.1.3.

This issue is not present in sphinx 1.2.2.

[Romain Chantereau (romain-m)]

But generate a WARNING at reference call

for instance:

.. program:: nova-manage

.. option:: db version

    Print the current database version.

:option:`nova-manage db version`

WARNING: Malformed :option: u'nova-manage db version', does not contain option marker - or -- or /

[Markus Zoeller (markus_z) (mzoeller)]

This wishlist bug has been open a year without any activity. I'm going
to move it to "Opinion / Wishlist", which is an easily-obtainable queue
of older requests that have come on. If you want to work on this,
just push a patch to Gerrit, there's no need to track this with a
bug report.

If there are any questions left, feel free to contact me (markus_z)
in the IRC channel #openstack-nova