Update package documentation

* Switched to Sphinx openstacktheme
* Rearranged docs along the OpenStack project lines
* Add Sphinx docs building job
* Added tox docs job

Change-Id: I069d3a95b90bc798b1dcc0331d6e24a6c08d1317

CONTRIBUTING.rst

@@ -0,0 +1,17 @@
+If you would like to contribute to the development of OpenStack, you must
+follow the steps in this page:
+
+   http://docs.openstack.org/infra/manual/developers.html
+
+If you already have a good understanding of how the system works and your
+OpenStack accounts are set up, you can skip to the development workflow
+section of this documentation to learn how changes to OpenStack should be
+submitted for review via the Gerrit tool:
+
+   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+
+Pull requests submitted through GitHub will be ignored.
+
+Bugs should be filed on StoryBoard, not GitHub:
+
+   https://storyboard.openstack.org/

doc/source/conf.py

@@ -31,7 +31,7 @@ sys.path.insert(0, os.path.abspath('.'))
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'openstackdocstheme']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -98,7 +98,8 @@ 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 = 'openstackdocs'
+
 
 # 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

doc/source/contributor/index.rst

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

doc/source/index.rst

@@ -1,17 +1,15 @@
-.. pyghmi documentation master file, created by
-   sphinx-quickstart on Tue Jun 18 09:15:24 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to pyghmi's documentation!
-=======================================
+.. include:: ../../README
 
-Contents:
+Documentation
+=============
 
 .. toctree::
-   :maxdepth: 2
+  :maxdepth: 2
 
-.. autoclass:: pyghmi.ipmi.command.Command
+  install/index
+  reference/index
+  contributor/index
 
 Indices and tables
 ==================
@@ -19,4 +17,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

doc/source/install/index.rst

@@ -0,0 +1,17 @@
+.. _installation:
+
+Installation
+============
+
+The pyghmi Python package can be downloaded and installed with *pip*:
+
+.. code-block:: bash
+
+   $ pip install pyhgmi
+
+Or, if you have virtualenvwrapper installed:
+
+.. code-block:: bash
+
+   $ mkvirtualenv pyghmi
+   $ pip install pyghmi

doc/source/reference/index.rst

@@ -0,0 +1,9 @@
+API reference 
+=============
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+.. autoclass:: pyghmi.ipmi.command.Command

lower-constraints.txt

@@ -1,6 +1,7 @@
 coverage===4.0
 cryptography===2.1
 fixtures===3.0.0
+openstackdocstheme==1.18.1
 oslotest===3.2.0
 python-subunit===1.0.0
 Sphinx===1.6.5

test-requirements.txt

@@ -3,6 +3,7 @@ coverage>=4.0
 fixtures>=3.0.0
 python-subunit>=1.0.0
 sphinx>=1.6.5
+openstackdocstheme>=1.18.1 # Apache-2.0
 stestr>=1.0.0 # Apache-2.0
 testscenarios>=0.4
 testtools>=2.2.0

tox.ini

@@ -34,6 +34,10 @@ commands =
     coverage html -d cover
     coverage xml -o cover/coverage.xml
 
+[testenv:docs]
+basepython = python3
+commands = python setup.py build_sphinx
+
 [testenv:venv]
 basepython = python3
 commands = {posargs}

zuul.d/project.yaml

@@ -1,7 +1,10 @@
 - project:
     check:
       jobs:
+        - build-openstack-sphinx-docs
         - openstack-tox-lower-constraints
+
     gate:
       jobs:
+        - build-openstack-sphinx-docs
         - openstack-tox-lower-constraints