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
This commit is contained in:
Jay Faulkner 2015-03-27 15:17:00 -07:00
parent 17067b938d
commit be97525975
7 changed files with 151 additions and 0 deletions

3
.gitignore vendored
View File

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

82
doc/source/conf.py Normal file
View File

@ -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'
),
]

35
doc/source/index.rst Normal file
View File

@ -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`

View File

@ -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')

View File

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

View File

@ -8,3 +8,8 @@ mock>=1.0
testrepository>=0.0.18 testrepository>=0.0.18
testtools>=0.9.36,!=1.2.0 testtools>=0.9.36,!=1.2.0
python-subunit>=0.0.18 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

View File

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