Clean up API documentation

Use explicit files instead of auto-generating them.

Fail the build on a warning.

Tweak titles and other headings.

Add instructions for using lockutils-wrapper.

Change-Id: Ie92ce14b33180d35d84bbd0998e61b659487481d
Don't use ConfigFilter for lockutils

In Neutron, we usually specify lock_path as:

lock_path = $state_path/lock

It turned out that ConfigFilter does not work correctly with
substitution feature, so its usage blocks Neutron adoption of the
library.

The issue is also not specific to Neutron: any deployer should be able
to use substitutions ($smth) in their configuration files without
determining whether those configuration options he's interested in are
defined as ConfigOpts or ConfigFilter.

So the best short term approach to push forward the adoption of the
library is to refrain from using ConfigFilter at least until there is
consensus on how to support substitution feature with the class.

Once oslo.config sorts the issue out, we may get back to using
ConfigFilter for lockutils.

Change-Id: I7b0b5c840381b2d9afc00ff116fee1d970743183
Closes-Bug: #1399897
Merge "Clean up API documentation"