reorder documentation

- reorder documentation so it's grouped logically.
- add api docstring modules

Change-Id: I47e49634fe7d8bb16a51f3045e7fe53683d56d1a

.gitignore

@@ -9,7 +9,7 @@ ChangeLog
 *.egg-info/
 build/
 doc/build/
-doc/source/api/autoindex.rst
+doc/source/api
 dist/
 .testrepository/
 .project

doc/ext/apidoc.py

@@ -0,0 +1,41 @@
+# Copyright 2013 OpenStack Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+import os.path as path
+
+from sphinx import apidoc
+
+
+# NOTE(gordc): pbr will run Sphinx multiple times when it generates
+# documentation. Once for each builder. To run this extension we use the
+# 'builder-inited' hook that fires at the beginning of a Sphinx build.
+# We use ``run_already`` to make sure apidocs are only generated once
+# even if Sphinx is run multiple times.
+run_already = False
+
+
+def run_apidoc(app):
+    global run_already
+    if run_already:
+        return
+    run_already = True
+
+    package_dir = path.abspath(path.join(app.srcdir, '..', '..', 'pycadf'))
+    source_dir = path.join(app.srcdir, 'api')
+    apidoc.main(['apidoc', package_dir, '-f',
+                 '-H', 'pyCADF Modules',
+                 '-o', source_dir])
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)

doc/source/api/index.rst

@@ -1,8 +0,0 @@
-==============
- API Reference
-==============
-
-.. toctree::
-   :maxdepth: 1
-
-   autoindex

doc/source/conf.py

@@ -13,6 +13,9 @@
 
 import sys, os
 
+# NOTE(gordc): path for Sphinx ext.apidoc
+sys.path.insert(0, os.path.abspath('..'))
+
 # This is required for ReadTheDocs.org, but isn't a bad idea anyway.
 os.environ['DJANGO_SETTINGS_MODULE'] = 'openstack_dashboard.settings'
 
@@ -35,7 +38,8 @@ extensions = [
     'sphinx.ext.coverage',
     'sphinx.ext.pngmath',
     'sphinx.ext.viewcode',
-    'oslosphinx'
+    'oslosphinx',
+    'ext.apidoc'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -136,7 +140,7 @@ html_theme_options = {
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.

doc/source/contributing.rst

@@ -0,0 +1,31 @@
+..
+      Copyright 2014 IBM Corp.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _contributing:
+
+=============
+ Contributing
+=============
+
+Contributions to the pyCADF library is welcomed.
+
+Important links:
+
+1. `Github repository`_
+
+2. `Launchpad project`_
+
+.. _Github repository: https://github.com/openstack/pycadf
+.. _Launchpad project: https://launchpad.net/pycadf

doc/source/index.rst

@@ -35,18 +35,30 @@ contribute to the project.
 
 .. _CADF (Cloud Audit Data Federation Working Group): http://www.dmtf.org/standards/cadf
 
-Table of contents
-=================
+Getting Started
+===============
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 1
 
-   api/index
-   specification/index
-   event_concept
-   middleware
+    event_concept
+    middleware
 
-.. update index
+Developer Documentation
+=======================
+
+.. toctree::
+    :maxdepth: 1
+
+    contributing
+    specification/index
+
+Code Documentation
+==================
+.. toctree::
+   :maxdepth: 1
+
+   api/modules
 
 Indices and tables
 ==================
@@ -54,8 +66,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
-To Do
-=====
-
-.. todolist::

setup.cfg

@@ -35,3 +35,9 @@ all_files = 1
 
 [upload_sphinx]
 upload-dir = doc/build/html
+
+[pbr]
+warnerrors = True
+#autodoc_tree_index_modules = True
+#autodoc_tree_root = ./pycadf
+