Hierarchical sphinx API documentation generation
Hierarchical sphinx API documentation generation

* Adding a new pbr boolean option 'autodoc_tree_index_modules' for
  creating a package/module hierarchy oriented API documentation.
* Using the sphinx.apidoc module in order to
  generate the *.rst files and the modules.rst.
  The sphinx.apidoc.main function call expected to be more future proof,
    than the other options.

Change-Id: I145086387edf6b042368d4c16dd64948f67606b0

openstack-dev/pbr,openstack-dev/pbr,redhat-openstack/pbr,openstack-dev/pbr,citrix-openstack-build/pbr,varunarya10/pbr,WiFast/pbr,redhat-openstack/pbr,citrix-openstack-build/pbr,citrix-openstack-build/pbr,klmitch/pbr,klmitch/pbr,JioCloud/pbr,WiFast/pbr,JioCloud/pbr,varunarya10/pbr