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