Style Guide and Validation Checks for Help and Config Strings

*** Introduction ***

Intended audience: Developers and writers who define or edit help strings in the python clients or in the configuration files.

Goal: Enforce conventions for help strings:

* Init-capitalize strings
* Add missing spaces between text
* End strings with "."
* Improve wording.

*** Components ***

1. Style guide that defines best practices for writing help and configuration strings.
2. Automation scripts that check help and configuration strings for writing style and formatting.

*** Style guide ***

The following is a sample of the style guide:

---------------------------------------
Style and format guide for help strings
---------------------------------------

This document provides style and format guidance for
the required help strings for Python clients and configuration code.

For the Python command-line clients, these help strings appear in
client command-line help and in
the `OpenStack Command Line Interface Reference
<http://docs.openstack.org/cli-reference/content/index.html>`_.

For configuration, they appear in sample configuration files and in
the `OpenStack Configuration Reference
<http://docs.openstack.org/havana/config-reference/content/>`_.

Writing style:
--------------

1. Use sentence-style capitalization, end each phrase or
   sentence with a period, and use single spaces between
   phrases or sentences. Examples::

   @utils.arg('--user-id', metavar='<USER_ID>',
              help='User to associate with sample.')

   @utils.arg('--timestamp', metavar='<TIMESTAMP>',
              help='The sample timestamp.')

   @utils.arg('--ok-action', dest='ok_actions',
              metavar='<Webhook URL>', action='append', default=None,
              help=('URL to invoke when state transitions to OK. '
              'May be used multiple times.'))

2. For subcommands, use the singular verb form. For example,
   for nova list, use 'Lists active servers' and not 'List active servers.'

3. For options, omit the verb. For example, for ``nova show <server>``,
   use 'Name or ID of server' and not 'Specifies the name or ID of server.'

4. For boolean options, use the phrase, 'Enables or disables.'
   For example, 'Enables or disables a specified user' and not
   'Specify True to enable a user.'

5. Properly capitalize words. See the `OpenStack Glossary <http://docs.openstack.org/glossary/>`_.

6. Use valid service names and API names. Valid service names include
   nova, cinder, swift, glance, heat, neutron, trove, ceilometer,
   horizon, keystone, and marconi.

   Valid API names include Compute API, Image Service API, Identity
   Service API, Object Storage API, Block Storage API, Database API,
   and Networking API.

7. For admin-only subcommands and options, add this text to the
   end of the help string: '(admin only, by default)'.

   Example::

   @utils.arg('--user-id', metavar='<USER_ID>',
              help='User to associate with sample (admin only, by default).')

   The 'by default' portion conveys that by default, only admin
   users can complete the action. However, the cloud operator
   can configure non-admin users to complete this action.

8. For the most part, avoid parenthetical text. Instead, use
   complete phrases or sentences for valid values, default values,
   and so on.

   Examples::

   @utils.arg('--user-id', metavar='<USER_ID>',
              help='User to associate with sample. Default is admin.')

   @utils.arg('--user-id', metavar='<USER_ID>',
              help='User to associate with sample. Valid values '
              are alphanumerical strings no longer than '
              12 characters.')

   However, if you do use a parenthetical phrase, include it at the end of
   the help string before the final period.

   Example::

   @utils.arg('--user-id', metavar='<USER_ID>',
              help='User to associate with sample (default is admin).')

Format:
-------

1. For multi-line strings, add a space at the end of
   every line except the last line. Example::

   @utils.arg('--user-id', metavar='<USER_ID>',
              help='User to associate '
              'with sample. This user must have admin '
              'privileges.)

*** Scripts ***

Where possible, create scripts that run automatically during build and that check these conventions:

* Ending period at the end of phrases and sentences.
* Extra space at end of line in multi-line help strings.
* Init capitalization.

*** Issues ***

* Where should the style guide reside? Proposal: hacking repository
* Where should the validation scripts reside? Proposal: hacking repository
* ??