Update documentation framework, add base devref details

- Add oslosphinx requirement
- Add base support for devref generation to the project
- Add basic level of documentation, with TODOs for future updates

Change-Id: I6798a4fdf380a56112c3b65350bf61dc410b32bd

doc/source/conf.py

@@ -18,7 +18,7 @@ import os
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../..'))
 
 # -- General configuration ------------------------------------------------
 
@@ -28,7 +28,10 @@ import os
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = [
+    'sphinx.ext.autodoc',
+    'oslosphinx'
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -44,7 +47,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'ceilometer-powervm'
-copyright = u'2015, Adam Reznechek, Drew Thorstensen'
+copyright = u'2015, IBM'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -74,11 +77,11 @@ exclude_patterns = ['_build']
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
+add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
-#add_module_names = True
+add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
@@ -98,7 +101,7 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+#html_theme = 'default'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -127,7 +130,7 @@ html_theme = 'default'
 # 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']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -137,6 +140,8 @@ html_static_path = ['_static']
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
+git_cmd = "git log --pretty=format:'%ad, commit %h' --date=local -n1"
+html_last_updated_fmt = os.popen(git_cmd).read()
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -176,28 +181,30 @@ html_static_path = ['_static']
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'ceilometer-powervmdoc'
+htmlhelp_basename = '%sdoc' % project
 
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-#'papersize': 'letterpaper',
+        # The paper size ('letterpaper' or 'a4paper').
+        #'papersize': 'letterpaper',
 
-# The font size ('10pt', '11pt' or '12pt').
-#'pointsize': '10pt',
+        # The font size ('10pt', '11pt' or '12pt').
+        #'pointsize': '10pt',
 
-# Additional stuff for the LaTeX preamble.
-#'preamble': '',
-}
+        # Additional stuff for the LaTeX preamble.
+        #'preamble': '',
+        }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  ('index', 'ceilometer-powervm.tex', u'ceilometer-powervm Documentation',
-   u'Adam Reznechek, Drew Thorstensen', 'manual'),
+    ('index',
+     '%s.tex' % project,
+     u'%s Documentation' % project,
+     u'IBM', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -226,8 +233,10 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'ceilometer-powervm', u'ceilometer-powervm Documentation',
-     [u'Adam Reznechek, Drew Thorstensen'], 1)
+    ('index',
+     '%s' % project,
+     u'%s Documentation' % project,
+     u'IBM', 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -240,9 +249,13 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'ceilometer-powervm', u'ceilometer-powervm Documentation',
-   u'Adam Reznechek, Drew Thorstensen', 'ceilometer-powervm', 'One line description of project.',
-   'Miscellaneous'),
+    ('index',
+     '%s' % project,
+     u'%s Documentation' % project,
+     u'IBM',
+     '%s' % project,
+     'PowerVM compute agent plugins for OpenStack Ceilometer',
+     'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -256,3 +269,4 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+