Add sphinx documentation

In support of building the docs without the sphinx Makefile this also adds as
tox.ini that can be used to build the docs via:

tox -e docs

A few updates to setup.cfg are needed as well to acount for deleting old
scripts.

Change-Id: Ifa852f9684998ee695188d3e72df7cdc3c5e063e

doc/source/baremetal-setup.rst

@@ -0,0 +1,84 @@
+Baremetal Environment Setup
+===========================
+
+instack-undercloud can be deployed in an all baremetal environment. One
+baremetal node will be used as the undercloud, and other available baremetal
+nodes will be used for the Overcloud deployment.
+
+Minimum System Requirements
+---------------------------
+
+In order to produce a usable OpenStack install this setup requires five
+baremetal machines: one machine for the undercloud, and one machine for each
+Overcloud node.
+
+.. image:: images/InstackSetup.png
+
+The setup requires baremetal machines with the following minimum specifications:
+
+* multi-core CPU
+* 4GB memory
+* 60GB free disk space
+
+The undercloud machine needs to run RHEL 7.1 x86_64, which is discussed more below.
+
+Preparing the Baremetal Environment
+-----------------------------------
+
+Networking
+^^^^^^^^^^
+
+The overcloud nodes will be deployed from the undercloud machine and therefore the machines need to have have their network settings modified to allow for the overcloud nodes to be PXE boot'ed using the undercloud machine. As such, the setup requires that:
+
+* All overcloud machines in the setup must support IPMI
+* A management provisioning network is setup for all of the overcloud machines.
+  One NIC from every machine needs to be in the same broadcast domain of the
+  provisioning network. In the tested environment, this required setting up a new
+  VLAN on the switch. Note that you should use the same NIC on each of the
+  overcloud machines ( for example: use the second NIC on each overcloud
+  machine). This is because during installation we will need to refer to that NIC
+  using a single name across all overcloud machines e.g. em2
+* The provisioning network NIC should not be the same NIC that you are using
+  for remote connectivity to the undercloud machine. During the undercloud
+  installation, a openvswitch bridge will be created for Neutron and the
+  provisioning NIC will be bridged to the openvswitch bridge. As such,
+  connectivity would be lost if the provisioning NIC was also used for remote
+  connectivity to the undercloud machine.
+* The overcloud machines can PXE boot off the NIC that is on the private VLAN.
+  In the tested environment, this required disabling network booting in the BIOS
+  for all NICs other than the one we wanted to boot and then ensuring that the
+  chosen NIC is at the top of the boot order (ahead of the local hard disk drive
+  and CD/DVD drives).
+* For each overcloud machine you have: the MAC address of the NIC that will PXE
+  boot on the provisioning network the IPMI information for the machine (i.e. IP
+  address of the IPMI NIC, IPMI username and password)
+
+Refer to the following diagram for more information
+
+.. image:: images/TripleO_Network_Diagram_.jpg
+
+Setting Up The Undercloud Machine
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. Select a machine within the baremetal environment on which to install the
+   undercloud.
+#. Install RHEL 7.1 x86_64 on this machine.
+#. If needed, create a non-root user with sudo access to use for installing the
+   Undercloud::
+
+        sudo useradd stack
+        sudo passwd stack  # specify a password
+        echo "stack ALL=(root) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/stack
+        sudo chmod 0440 /etc/sudoers.d/stack
+
+#. Download and execute the instack-undercloud setup script::
+
+    curl https://raw.githubusercontent.com/rdo-management/instack-undercloud/master/scripts/instack-setup-host-rhel7 | bash -x
+
+#. Copy the sample instack answers file to the home directory::
+
+    cp instack-undercloud/instack.answers.sample ~/instack.answers
+
+#. Edit the ``instack.answers`` file appropriately.
+
+#. Create a json file describing your baremetal nodes.

doc/source/build-images.rst

@@ -0,0 +1,31 @@
+Building Images
+===============
+
+Images must be built prior to doing a deployment. A discovery ramdisk,
+deployment ramdisk, and openstack-full image can all be built using
+instack-undercloud.
+
+It's recommended to build images on the installed undercloud directly since all
+the dependencies are already present.
+
+The following steps can be used to build images. They should be run as the same
+non-root user that was used to install the undercloud.
+
+#. Source rhel7rc to set appropriate environment variables::
+
+    source instack-undercloud/rhel7rc
+
+#. Download the rhel7 cloud image or copy it from another host to the
+   undercloud::
+
+    curl -O http://download.devel.redhat.com/brewroot/packages/rhel-guest-image/7.0/20140930.0/images/rhel-guest-image-7.0-20140930.0.x86_64.qcow2
+
+#. Build the 3 image types::
+
+    instack-undercloud/scripts/instack-build-images deploy-ramdisk
+    instack-undercloud/scripts/instack-build-images discovery-ramdisk
+    instack-undercloud/scripts/instack-build-images openstack-full
+
+#. Load the images into Glance::
+
+    instack-undercloud/scripts/instack-prepare-for-overcloud

doc/source/conf.py

@@ -0,0 +1,242 @@
+# -*- coding: utf-8 -*-
+#
+# instack-undercloud documentation build configuration file, created by
+# sphinx-quickstart on Wed Feb 25 10:56:57 2015.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'instack-undercloud'
+copyright = u'2015, RDO'
+
+# 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.
+version = '2.0.0'
+# The full version, including alpha/beta/rc tags.
+release = '2.0.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# 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
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# 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
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'instack-underclouddoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'instack-undercloud.tex', u'instack-undercloud Documentation',
+   u'RDO', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'instack-undercloud', u'instack-undercloud Documentation',
+     [u'RDO'], 1)
+]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'instack-undercloud', u'instack-undercloud Documentation',
+   u'RDO', 'instack-undercloud', 'One line description of project.',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'

doc/source/deploy-overcloud.rst

@@ -0,0 +1,36 @@
+Deploying the Overcloud
+=======================
+
+All the commands on this page require that the appropriate stackrc file has
+been sourced into the environment::
+
+    source stackrc
+
+Registering Nodes
+-----------------
+
+Register nodes for your deployment with Ironic::
+
+    instack-undercloud/scripts/instack-ironic-deployment --nodes-json instackenv.json --register-nodes
+
+Disovering Nodes
+----------------
+
+Discover hardware attributes of nodes and match them to a deployment profile::
+
+    instack-undercloud/scripts/instack-ironic-deployment --discover-nodes
+
+Check what profiles were matched for the discovered nodes::
+
+    instack-undercloud/scripts/instack-ironic-deployment --show-profile
+
+Deploying Nodes
+---------------
+
+Create the necessary flavors::
+
+    instack-undercloud/scripts/instack-ironic-deployment --setup-flavors
+
+Deploy the the *openstack-full* image to 3 nodes::
+
+    COMPUTE_COUNT=3 CONTROL_COUNT=0 instack-undercloud/scripts/instack-ironic-deployment --deploy-nodes

doc/source/index.rst

@@ -0,0 +1,25 @@
+.. instack-undercloud documentation master file, created by
+   sphinx-quickstart on Wed Feb 25 10:56:57 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to instack-undercloud's documentation!
+==============================================
+
+Contents:
+
+.. toctree::
+
+   Introduction <intro>
+   Setup <setup>
+   Installing the Undercloud <install-undercloud>
+   Building Images <build-images>
+   Deploying the Overcloud <deploy-overcloud>
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/source/install-undercloud.rst

@@ -0,0 +1,31 @@
+Installing the Undercloud
+=========================
+
+Make sure you are logged in as a non-root user (such as the stack user) on the
+node on which you want to install the undercloud.
+
+If you used the virt setup this node will be a VM called *instack* and you can
+use the stack user.
+
+For a baremetal setup this will be the host you selected for the Undercloud
+while preparing the environment.
+
+#. Download and execute the instack-undercloud setup script::
+
+    curl https://raw.githubusercontent.com/rdo-management/instack-undercloud/master/scripts/instack-setup-host-rhel7 | bash -x
+
+#. Source rhel7rc to set appropriate environment variables::
+
+    source instack-undercloud/rhel7rc
+
+#. Run script to install the undercloud::
+
+    instack-undercloud/scripts/instack-install-undercloud
+
+Once the install script has run to completion, you should take note of the
+files ``/root/stackrc`` and ``/root/tripleo-undercloud-passwords``. Both these
+files will be needed to interact with the installed undercloud. Copy them to
+the home directory for easier use later.::
+
+    sudo cp /root/tripleo-undercloud-passwords .
+    sudo cp /root/stackrc .

doc/source/intro.rst

@@ -0,0 +1,7 @@
+Introduction
+============
+
+instack-undercloud is a scripted installer and other tooling for OpenStack
+based on `TripleO`_.
+
+.. _Tripleo: https://wiki.openstack.org/wiki/TripleO

doc/source/setup.rst

@@ -0,0 +1,7 @@
+Setup
+=====
+
+.. toctree::
+
+   Virtual Environment Setup <virt-setup>
+   Baremetal Environment Setup <baremetal-setup>

doc/source/virt-setup.rst

@@ -0,0 +1,97 @@
+Virtual Environment Setup
+=========================
+
+instack-undercloud can be deployed in a virtual environment using virtual
+machines instead of actual baremetal. One baremetal machine is still needed to
+act as the host for the virtual machines.
+
+instack-undercloud contains the necessary tooling to create and configure the
+environment.
+
+Minimum System Requirements
+---------------------------
+
+This setup creates 5 virtual machines consisting of 4GB of memory and 40GB of
+disk space on each. The virtual machine disk files are thinly provisioned and
+will not take up the full 40GB initially.
+
+The minimum system requirements for the virtual host machine are:
+
+* A baremetal machine with virtualization hardware extenstions enabled.
+  Nested KVM is **not** supported.
+* At least (1) quad core CPU
+* 12GB free memory
+* 120GB disk space [#]_
+
+If you want to increase the scaling of one or more overcloud nodes, you will
+need to ensure you have enough memory and disk space.
+
+Preparing the Host Machine
+--------------------------
+
+#. Make sure sshd service is installed and running.
+#. The user performing all of the installation steps on the virt host needs to
+   have sudo enabled. You can use an existing user or use the following commands
+   to create a new user called stack with password-less sudo enabled. Do not run
+   the rest of the steps in this guide as root.
+
+    * Example commands to create a user::
+
+        sudo useradd stack
+        sudo passwd stack  # specify a password
+        echo "stack ALL=(root) NOPASSWD:ALL" | sudo tee -a /etc/sudoers.d/stack
+        sudo chmod 0440 /etc/sudoers.d/stack
+
+#. Make sure you are logged in as the non-root user you intend to use.
+#. Add export of LIBVIRT_DEFAULT_URI to your bashrc file::
+
+    echo 'export LIBVIRT_DEFAULT_URI="qemu:///system"' >> ~/.bashrc
+
+#. Download and execute the instack-undercloud setup script::
+
+    curl https://raw.githubusercontent.com/rdo-management/instack-undercloud/master/scripts/instack-setup-host-rhel7 | bash -x
+
+#. Run scripts to install required dependencies::
+
+    source /usr/libexec/openstack-tripleo/devtest_variables.sh
+    tripleo install-dependencies
+    tripleo set-usergroup-membership
+    # The previous command has added the user to the libvirtd group, so we need to login to the new group
+    newgrp libvirtd
+    newgrp
+
+#. Download the RHEL 7.1 cloud image or copy it over from a different
+   location::
+
+    curl -O http://download.devel.redhat.com/brewroot/packages/rhel-guest-image/7.1/20150203.1/images/rhel-guest-image-7.1-20150203.1.x86_64.qcow2
+
+#. Source rhel7rc to set appropriate environment variables::
+
+    source instack-undercloud/rhel7rc
+    export DIB_YUM_REPO_CONF=/etc/yum.repos.d/rhos-release-6-rhel-7.1.repo
+    export NODE_DIST=rhel7
+
+#. Run the script to setup your virtual environment::
+
+    instack-undercloud/scripts/instack-virt-setup
+
+When the script has completed successfully it will output the IP address of the
+instack vm that has now been installed with a base OS.
+
+Running virsh list --all will show you now have one virtual machine called
+*instack* and 4 called *baremetal[0-3]*.
+
+You can ssh to the instack vm as the root user::
+
+        ssh root@<instack-vm-ip>
+
+The vm contains a ``stack`` user to be used for installing the undercloud. You
+can ``su - stack`` to switch to the stack user account.
+
+.. rubric:: Footnotes
+
+.. [#]  Note that some default partitioning scheme will most likely not provide
+    enough space to the partition containing the default path for libvirt image
+    storage (/var/lib/libvirt/images). The easiest fix is to customize the
+    partition layout at the time of install to provide at least 200 GB of space for
+    that path.

setup.cfg

@@ -26,10 +26,8 @@ scripts =
     scripts/instack-delete-overcloud
     scripts/instack-deploy-overcloud
     scripts/instack-install-undercloud
-    scripts/instack-install-undercloud-source
     scripts/instack-ironic-deployment
     scripts/instack-prepare-for-overcloud
-    scripts/instack-setup-delorean
     scripts/instack-setup-host-rhel7
     scripts/instack-test-overcloud
     scripts/instack-update-overcloud

test-requirements.txt

@@ -0,0 +1,2 @@
+oslosphinx
+sphinx>=1.1.2,<1.2

tox.ini

@@ -0,0 +1,24 @@
+[tox]
+minversion = 1.6
+skipsdist = True
+
+[testenv]
+usedevelop = True
+install_command = pip install {opts} {packages}
+setenv = VIRTUAL_ENV={envdir}
+deps = -r{toxinidir}/test-requirements.txt
+
+[testenv:venv]
+commands = {posargs}
+
+[testenv:docs]
+commands = python setup.py build_sphinx
+
+[testenv:pep8]
+deps = bashate
+whitelist_externals = bash
+commands = bash -c "find scripts -type f | xargs bashate -v"
+
+[flake8]
+ignore = H803
+exclude = .tox