Merge "Improve doc formatting a bit"

README.rst

@@ -17,6 +17,8 @@ library, and adding logic and features that the OpenStack Infra team had
 developed to run client applications at scale, it turned out that we'd written
 nine-tenths of what we'd need to have a standalone library.
 
+.. _example:
+
 Example
 =======
 

doc/source/index.rst

@@ -3,6 +3,7 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+=================================
 Welcome to shade's documentation!
 =================================
 
@@ -14,6 +15,11 @@ Contents:
    install/index
    user/index
    contributor/index
+
+.. releasenotes contains a lot of sections, toctree with maxdepth 1 is used.
+.. toctree::
+   :maxdepth: 1
+
    releasenotes/index
 
 .. include:: ../../README.rst

doc/source/user/usage.rst

@@ -6,6 +6,8 @@ To use shade in a project::
 
 	import shade
 
+For a simple example, see :ref:`example`.
+
 .. note::
   API methods that return a description of an OpenStack resource (e.g.,
   server instance, image, volume, etc.) do so using a `munch.Munch` object