From be975259758f8c58e5b6c72ff99878579aa9b37d Mon Sep 17 00:00:00 2001 From: Jay Faulkner Date: Fri, 27 Mar 2015 15:17:00 -0700 Subject: [PATCH] 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 | 3 ++ doc/source/conf.py | 82 ++++++++++++++++++++++++++++++++++ doc/source/index.rst | 35 +++++++++++++++ ironic_python_agent/version.py | 18 ++++++++ setup.cfg | 1 + test-requirements.txt | 5 +++ tox.ini | 7 +++ 7 files changed, 151 insertions(+) create mode 100644 doc/source/conf.py create mode 100644 doc/source/index.rst create mode 100644 ironic_python_agent/version.py diff --git a/.gitignore b/.gitignore index 53ef7fa78..cade2d66b 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,6 @@ imagebuild/coreos/dist imagebuild/coreos/oem/authorized_keys imagebuild/coreos/UPLOAD *.swp +_build +doc/source/api/ +doc/build diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 000000000..df8dd0c6c --- /dev/null +++ b/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' + ), +] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 000000000..f89fd9e9d --- /dev/null +++ b/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` diff --git a/ironic_python_agent/version.py b/ironic_python_agent/version.py new file mode 100644 index 000000000..9082d81ef --- /dev/null +++ b/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') diff --git a/setup.cfg b/setup.cfg index 80171b0e3..108044490 100644 --- a/setup.cfg +++ b/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 diff --git a/test-requirements.txt b/test-requirements.txt index 85e46e726..50847e96a 100644 --- a/test-requirements.txt +++ b/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 diff --git a/tox.ini b/tox.ini index 83ea18cc8..0e100186b 100644 --- a/tox.ini +++ b/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