Implemented support for custom opt types

Motivation:

Currently oslo.config supports only basic set of types:
strings, integers, floats, booleans, lists of strings and
dictionaries of strings. The reason of existence of types
other than string is to provide some kind of value
validation (e.g. that integer contains only digits).
There is a demand in community to have more complex value
checks, e.g. that a port configuration option contains
integer value that fits in certain range, host ip address
conforms to ip address format, etc.

Solution:

This patch introduces support for custom Opt types that
will allow a better control of value conversion and
validation. Custom types are presented as type
constructors - callable objects that take a string and
either return converted value or raise ValueError in
case value can't be converted. This concept is similar to
argument types in 'argparse' library.
Type constructor can be a class which instances are
callable, a function or any callable object (which allows
usage of parametriezed type class instances).

Details:

Oslo.config has Opt subclasses that control value
conversion and validation: StrOpt, IntOpt, FloatOpt, etc.
The type information is added to the base class - Opt -
cause otherwise it would introduce confusion on what class
to use when introducing e.g. NetworkPort: StrOpt or IntOpt.
For each existing Opt subclass a corresponding type was
implemented (see oslo.config.types).  StrOpt, IntOpt, etc.
classes are left for backward compatibility and present an
Opt class parametrized with particular type.

There are two exceptions of this rule: BoolOpt and
MultiStrOpt. Those classes define a special logic for
parsing values. BoolOpt was left unchanged and should be
used when someone wants a Boolean option that is available
through CLI.
MultiStrOpt has logic to accumulate values. As it was bound
to String type only, it's logic was extracted into a
MultiOpt class and MultiStrOpt was left as a subclass
parametrized with String type.

Opt values allow value substitution. Previously it worked
only for string types but now this feature only makes sense
if it would work on any type. _substitute() and _do_get()
methods of ConfigOpts class were updated to cover that.
Also, TemplateSubstitution tests were updated to ensure
that substitution is done before type conversion kicks in
or otherwise type conversion will fail (e.g. if Integer
type converted will get something like '$listen_port').

Advised review steps:

1. New type classes (oslo/config/types.py) and their tests
   (tests/test_types.py);
2. Changes to Str/Bool/Int/etc-Opt classes
   (those are pretty straight forward);
3. Other changes that add support for new types into
   existing infrastructure;
4. New cfg test cases added (mostly related to changes in
   substitution mechanics).

blueprint oslo-config-options-validation

Change-Id: I6910f1efa540cfe757b2be6da0aec072f8ed28fa
Remove copyright from empty files

According to policy change in HACKING:
http://docs.openstack.org/developer/hacking/#openstack-licensing
empty files should no longer contain copyright notices.

Closes-Bug: #1262424
Change-Id: Id6396fc396376c7e8bb0c8eb4abe472a97c014c5
Merge "Implemented support for custom opt types"
Throw exception if --config-dir doesn't exist

Currently an invalid --config-dir option is silently ignored.
This means that a user could accidentally enter the wrong
directory or have a typo which would cause the desired
config files to not be used and no indication of the error would be
produced.

This change adds a ConfigDirNotFoundError exception that can be
raised when the requested --config-dir isn't found.

While working out the unit tests for this it was discovered that
the test_config_dir_tilde test case was not correct.  It could still
pass when it should fail.  This commit includes a fix for that issue
as well.

Closes-bug: 1255354
Change-Id: I386b2419d04572b14ccf11b527f871a237304e53
Merge "Remove copyright from empty files"
Merge "Throw exception if --config-dir doesn't exist"
Add docs for types

Add a page to pull in the docstrings for the option types,
and make the docstring changes in the module necessary for
that to work properly.

Also fix a formatting issue in the docs for the cfg module.

Change-Id: Ib1cf24e59ecc3592d3b703f99659f4a0fdbc7f5c
Add Style Guide for help of config options

This is an initial document on how the config options should be written
and formatted.

Change-Id: Ic838a322ec4c1fc7b2507ecb126ef372617d0fc5
Support building wheels (PEP-427)

Universal is used to identify pure-Python module(by bdist_wheel). For
these, it is sufficient to build a wheel with _any_ Python ABI version
and publish that to PyPI (by whatever means).

Change-Id: Ieabefc1fc8c8fbcd8749c07ccabb1ff88e1a761e
Fix misspellings in oslo.config

Fix misspellings detected by:
* pip install misspellings
* git ls-files | grep -v locale | misspellings -f -

Change-Id: I96a3e5717cbce66c19ead15a9e491fe4a44f6e88
Closes-Bug: #1257295
Merge "Add docs for types"
Merge "Fix misspellings in oslo.config"
Merge "Support building wheels (PEP-427)"
Remove extraneous vim configuration comments

Remove line containing

comment - # vim: tabstop=4 shiftwidth=4 softtabstop=4

Change-Id: I6e486876d5743bfbfb3a93c89f6da81c32d22ffd
Closes-Bug:#1229324
Switch over to oslosphinx

Having the sphinx theme in the same namespace package
as the production code has been causing issues with
devstack installations. The solution settled on was
to rename oslo.sphinx to oslosphinx because oslo.sphinx
is not a "production" library.

See the linked bug report for more background details.

Closes-Bug: #1277168
Change-Id: I419fe50d66fa0c1ac48deca2286ae7c4b922d72d
Fix docstring of parsing order

There is wrong explaination of option parsing order in config files
and on command line. That is only the later one takes action.
The sample code shows only the later one takes action.
See http://paste.openstack.org/show/64229/

Change-Id: I4d48df1b551bb130dc25fe32303fa2d0b1fecffd
Merge "Remove extraneous vim configuration comments"
Merge "Fix docstring of parsing order"