Add sphinx build + basic documentation

This adds and configures a sphinx doc builder. This is based on the code
in Ironic to build documentation.

The goal is for this to contain development documentation relevant to
hacking on the agent, including how to make custom HardwareManagers.

Change-Id: Ib6cecb9959f4ad5c71440fb37827b996582a9545

.gitignore

@@ -15,3 +15,6 @@ imagebuild/coreos/dist
 imagebuild/coreos/oem/authorized_keys
 imagebuild/coreos/UPLOAD
 *.swp
+_build
+doc/source/api/
+doc/build

doc/source/conf.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+#
+
+# -- General configuration ----------------------------------------------------
+
+# 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.viewcode',
+              'sphinxcontrib.httpdomain',
+              'sphinxcontrib.pecanwsme.rest',
+              'wsmeext.sphinxext',
+              'oslosphinx',
+              ]
+
+wsme_protocols = ['restjson']
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Ironic Python Agent'
+copyright = u'OpenStack Foundation'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+from ironic_python_agent import version as ipa_version
+# The full version, including alpha/beta/rc tags.
+release = ipa_version.version_info.release_string()
+# The short X.Y version.
+version = ipa_version.version_info.version_string()
+
+# A list of ignored prefixes for module index sorting.
+modindex_common_prefix = ['ironic_python_agent']
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+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
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- Options for HTML output --------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+#html_theme_path = ["."]
+#html_theme = '_theme'
+#html_static_path = ['_static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = '%sdoc' % project
+
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass
+# [howto/manual]).
+latex_documents = [
+    (
+        'index',
+        '%s.tex' % project,
+        u'%s Documentation' % project,
+        u'OpenStack Foundation',
+        'manual'
+    ),
+]

doc/source/index.rst

@@ -0,0 +1,35 @@
+=============================================
+Welcome to Ironic-Python-Agent documentation!
+=============================================
+
+Introduction
+============
+
+An agent for controlling and deploying Ironic controlled baremetal nodes.
+
+The ironic-python-agent works with the agent driver in Ironic to provision
+nodes. Starting with ironic-python-agent running on a ramdisk on the
+unprovisioned node, Ironic makes API calls to ironic-python-agent to provision
+the machine. This allows for greater control and flexibility of the entire
+deployment process.
+
+The ironic-python-agent may also be used with the original Ironic pxe driver
+as of the Kilo OpenStack release.
+
+Developer Guide
+===============
+
+Generated Developer Documentation
+---------------------------------
+
+.. toctree::
+  :maxdepth: 0
+
+  api/autoindex
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

ironic_python_agent/version.py

@@ -0,0 +1,18 @@
+# Copyright 2011 OpenStack Foundation
+# 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.
+
+import pbr.version
+
+version_info = pbr.version.VersionInfo('ironic_python_agent')

setup.cfg

@@ -1,5 +1,6 @@
 [metadata]
 name = ironic-python-agent
+version = 0.1
 author = OpenStack
 author-email = openstack-dev@lists.openstack.org
 summary = Ironic Python Agent Ramdisk

test-requirements.txt

@@ -8,3 +8,8 @@ mock>=1.0
 testrepository>=0.0.18
 testtools>=0.9.36,!=1.2.0
 python-subunit>=0.0.18
+
+# Doc requirements
+sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
+sphinxcontrib-pecanwsme>=0.8
+oslosphinx>=2.5.0,<2.6.0  # Apache-2.0

tox.ini

@@ -31,6 +31,13 @@ commands = {posargs:}
 envdir = devenv
 usedevelop = True
 
+[testenv:gendocs]
+setenv = PYTHONHASHSEED=0
+sitepackages = False
+envdir = {toxworkdir}/venv
+commands =
+  python setup.py build_sphinx
+
 [flake8]
 # E711: ignored because it is normal to use "column == None" in sqlalchemy