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

.gitignore

@@ -3,3 +3,4 @@
 .tox/
 ceilometer_powervm.egg-info/
 *.pyc
+doc/build

CONTRIBUTING.rst

@@ -1,3 +1,5 @@
+Contributing to Ceilometer-PowerVM
+==================================
 If you would like to contribute to the development of OpenStack,
 you must follow the steps in the "If you're a developer, start here"
 section of this page:

README.rst

@@ -1,6 +1,6 @@
-=========================================================
+==========================================
 Support for PowerVM Performance Monitoring
-=========================================================
+==========================================
 
 Include the URL of your launchpad blueprint:
 

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,7 +181,7 @@ 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 ---------------------------------------------
@@ -196,8 +201,10 @@ latex_elements = {
 # (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,8 +249,12 @@ 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.',
+    ('index',
+     '%s' % project,
+     u'%s Documentation' % project,
+     u'IBM',
+     '%s' % project,
+     'PowerVM compute agent plugins for OpenStack Ceilometer',
      'Miscellaneous'),
 ]
 
@@ -256,3 +269,4 @@ texinfo_documents = [
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+

doc/source/contributing.rst

@@ -1 +0,0 @@
-.. include:: ../../CONTRIBUTING.rst

doc/source/devref/development_environment.rst

@@ -0,0 +1,45 @@
+..
+      Copyright 2015 IBM
+      All Rights Reserved.
+
+      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.
+
+Setting Up a Development Environment
+====================================
+
+This page describes how to setup a working Python development
+environment that can be used in developing ceilometer-powervm.
+
+These instructions assume you're already familiar with
+Git and Gerrit, which is a code repository mirror and code review toolset,
+however if you aren't please see `this Git tutorial`_ for an introduction
+to using Git and `this guide`_ for a tutorial on using Gerrit and Git for
+code contribution to Openstack projects.
+
+.. _this Git tutorial: http://git-scm.com/book/en/Getting-Started
+.. _this guide: http://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Getting the code
+----------------
+
+Grab the code::
+
+    git clone git://git.openstack.org/stackforge/ceilometer-powervm
+    cd ceilometer-powervm
+
+Setting up your environment
+---------------------------
+
+.. todo::
+
+    Add in steps for environment setup

doc/source/devref/index.rst

@@ -0,0 +1,47 @@
+..
+      Copyright 2015 IBM
+      All Rights Reserved.
+
+      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.
+
+Developer Guide
+===============
+
+In the Developer Guide, you will find information on how to develop for
+Ceilometer-PowerVM and how it interacts with Ceilometer. You will also find
+information on setup and usage of Ceilometer-PowerVM.
+
+
+Internals and Programming
+-------------------------
+.. toctree::
+    :maxdepth: 3
+
+    development_environment
+    usage
+
+
+Testing
+-------
+.. toctree::
+    :maxdepth: 3
+
+    testing
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/source/devref/testing.rst

@@ -0,0 +1,65 @@
+..
+      Copyright 2015 IBM
+      All Rights Reserved.
+
+      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.
+
+Running Ceilometer-PowerVM Tests
+================================
+
+This page describes how to run the Ceilometer-PowerVM tests. This page assumes you
+have already set up an working Python environment for Ceilometer-PowerVM development.
+
+With `tox`
+~~~~~~~~~~
+
+Ceilometer-PowerVM, like other OpenStack projects, uses `tox`_ for managing the virtual
+environments for running test cases. It uses `Testr`_ for managing the running
+of the test cases.
+
+Tox handles the creation of a series of `virtualenvs`_ that target specific
+versions of Python.
+
+Testr handles the parallel execution of series of test cases as well as
+the tracking of long-running tests and other things.
+
+For more information on the standard tox-based test infrastructure used by
+OpenStack and how to do some common test/debugging procedures with Testr,
+see this wiki page:
+
+  https://wiki.openstack.org/wiki/Testr
+
+.. _Testr: https://wiki.openstack.org/wiki/Testr
+.. _tox: http://tox.readthedocs.org/en/latest/
+.. _virtualenvs: https://pypi.python.org/pypi/virtualenv
+
+PEP8 and Unit Tests
++++++++++++++++++++
+
+Running pep8 and unit tests is as easy as executing this in the root
+directory of the Ceilometer-PowerVM source code::
+
+    tox
+
+To run only pep8::
+
+    tox -e pep8
+
+Since pep8 includes running pylint on all files, it can take quite some time to run.
+To restrict the pylint check to only the files altered by the latest patch changes::
+
+    tox -e pep8 HEAD~1
+
+To run only the unit tests::
+
+    tox -e py27

doc/source/devref/usage.rst

@@ -0,0 +1,21 @@
+..
+      Copyright 2015 IBM
+      All Rights Reserved.
+
+      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.
+
+Usage
+=====
+- Install the ceilometer-powervm plugin on the compute server
+- Set the hypervisor_inspector in the ceilometer.conf to "powervm"
+- Start the ceilometer-agent-compute on the compute server

doc/source/index.rst

@@ -1,18 +1,45 @@
-Welcome to ceilometer-powervm's documentation!
+..
+      Copyright 2015 IBM
+      All Rights Reserved.
+
+      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.
+
+Welcome to Ceilometer-PowerVM's documentation!
 ==============================================
 
-This project will provide Ceilometer-compatible compute agent plugins for
-monitoring instance utilization and statistics on managed systems.
+This project will provide Ceilometer-compatible compute agent plugins
+for monitoring instance utilization and statistics on PowerVM systems.
+
+Documentation on Ceilometer can be found at the `Ceilometer documentation`_.
+
+.. _`Ceilometer documentation`: http://docs.openstack.org/developer/ceilometer
+
+Ceilometer-PowerVM Policies
+===========================
 
 Contents:
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
+   policies/index
 
+Ceilometer-PowerVM Devref
+=========================
 
-Indices and tables
-==================
+Contents:
 
-* :ref:`search`
+.. toctree::
+   :maxdepth: 1
 
+   devref/index

doc/source/policies/bugs.rst

@@ -0,0 +1,26 @@
+Ceilometer-PowerVM Bugs
+=======================
+
+Ceilometer-PowerVM maintains all of its bugs in `Launchpad <https://bugs.launchpad.net/ceilometer-powervm>`_.
+All of the current open Ceilometer-PowerVM bugs can be found in that link.
+
+Bug Triage Process
+------------------
+
+The process of bug triaging consists of the following steps:
+
+1. Check if a bug was filed for a correct component (project). If not, either change the project
+   or mark it as "Invalid".
+2. Add appropriate tags. Even if the bug is not valid or is a duplicate of another one, it still
+   may help bug submitters and corresponding sub-teams.
+3. Check if a similar bug was filed before. If so, mark it as a duplicate of the previous bug.
+4. Check if the bug description is consistent, e.g. it has enough information for developers to
+   reproduce it. If it's not consistent, ask submitter to provide more info and mark a bug as
+   "Incomplete".
+5. Depending on ease of reproduction (or if the issue can be spotted in the code), mark it as
+   "Confirmed".
+6. Assign the importance. Bugs that obviously break core and widely used functionality should get
+   assigned as "High" or "Critical" importance. The same applies to bugs that were filed for gate
+   failures.
+7. (Optional). Add comments explaining the issue and possible strategy of fixing/working around
+   the bug.

doc/source/policies/code-reviews.rst

@@ -0,0 +1,13 @@
+Code Reviews
+============
+
+Code reviews are a critical component of all OpenStack projects. Code reviews provide a
+way to enforce a level of consistency across the project, and also allow for the careful
+onboarding of contributions from new contributors.
+
+Code Review Practices
+---------------------
+Ceilometer-PowerVM follows the `code review guidelines <https://wiki.openstack.org/wiki/ReviewChecklist>`_ as
+set forth for all OpenStack projects. It is expected that all reviewers are following the guidelines
+set forth on that page.
+

doc/source/policies/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../../../CONTRIBUTING.rst

doc/source/policies/index.rst

@@ -0,0 +1,40 @@
+..
+      Copyright 2015 IBM
+      All Rights Reserved.
+
+      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.
+
+Ceilometer-PowerVM Policies
+===========================
+
+In the Policies Guide, you will find documented policies for developing with
+Ceilometer-PowerVM. This includes the processes we use for blueprints and specs,
+bugs, contributor onboarding, and other procedural items.
+
+Policies
+--------
+.. toctree::
+    :maxdepth: 3
+
+    bugs
+    contributing
+    code-reviews
+    readme
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/source/policies/readme.rst

@@ -0,0 +1 @@
+.. include:: ../../../README.rst

doc/source/readme.rst

@@ -1 +0,0 @@
-.. include:: ../../README.rst

requirements.txt

@@ -1,4 +1,3 @@
 oslo.log>=1.2.0  # Apache-2.0
 pbr>=0.11,<2.0
-sphinx>=1.1.2,<1.2
 yasfb>=0.5.1

test-requirements.txt

@@ -8,4 +8,6 @@ testrepository>=0.0.18
 testscenarios>=0.4
 testtools>=0.9.36,!=1.2.0
 oslotest>=1.5.1  # Apache-2.0
+sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
+oslosphinx>=2.5.0  # Apache-2.0
 mock>=1.0