Set the pbr option 'warnerrors' to make build_sphinx turns warnings into
error. Fix all warnings.
`tox -edocs` will thus abort whenever someone introduce a new error.
Change-Id: Id6d09768a241866e1fdc1a1e2bf90336f5c5087d
Our docs are very developer focused. Lets create a separate user guide
to help new users get started.
Change-Id: I8a03920e6d3306dd0405177875ea55ccb4b40fea
Rework the list as a definition list.
Mark literal code snippets as literal code snippets.
Fix heading typo.
Change-Id: Ie3d393a49914779f12f3075ff2ac2df5ecf78321
This makes the docs site a lot more manageable and begins moving us in
the direction of separate user and developer docs.
Change-Id: I1650ef9d5be1733b8bc118d99090143cb5b06102