Clean up heat-agents docs

Improve links, formatting, grammar.

Change-Id: I459b40f30ccd613e19d20e342948f19be1f01efd

doc/source/contributor/index.rst

@@ -1,8 +0,0 @@
-===========================
-Contributing to Heat Agents
-===========================
-
-This contains policies for developing with heat-agents.
-
-.. toctree::
-   :maxdepth: 1

doc/source/index.rst

@@ -1,42 +1,27 @@
-.. heat-agents documentation master file, created by
+Heat Agents
-   sphinx-quickstart on Thu Jul 20 08:52:00 2017.
+===========
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to Heat Agents!
+Heat Agents are python hooks for deploying software configurations using
-=======================
+`Heat`_.
-
-Overview
-========
-
-Heat Agents are python hooks for deploying software configurations using heat.
 
 
-This repository contains `diskimage-builder <https://github.com/openstack/diskimage-builder>`_
+This repository contains `diskimage-builder`_ elements to build an image with
-elements to build an image with the software configuration hooks
+the software configuration hooks required to use your preferred configuration
-required to use your preferred configuration method.
+method.
 
-These elements depend on some elements found in the
+These elements depend on some elements found in the `tripleo-image-elements`_
-`tripleo-image-elements <https://github.com/openstack/tripleo-image-elements>`_
+repository. These elements will build an image which uses `os-collect-config`_,
-repository. These elements will build an image which uses
+`os-refresh-config`_, and `os-apply-config`_ together to invoke a hook with the
-`os-collect-config <https://github.com/openstack/os-collect-config>`_,
+supplied configuration data, and return any outputs back to Heat.
-`os-refresh-config <https://github.com/openstack/os-refresh-config>`_, and
-`os-apply-config <https://github.com/openstack/os-apply-config>`_ together to
-invoke a hook with the supplied configuration data, and return any outputs back
-to heat.
 
+.. _Heat: https://docs.openstack.org/heat/latest
+.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/
+.. _tripleo-image-elements: https://git.openstackorg/cgit/openstack/tripleo-image-elements
+.. _os-collect-config: https://git.openstackorg/cgit/openstack/os-collect-config
+.. _os-refresh-config: https://git.openstackorg/cgit/openstack/os-refresh-config
+.. _os-apply-config: https://git.openstackorg/cgit/openstack/os-apply-config
 
-Index
-=====
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 3
 
    install/index
-   contributor/index
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`search`

doc/source/install/building_image.rst

@@ -1,14 +1,13 @@
-=============================================
+================================================
-Build image with software configuration hooks
+Building an image with software deployment hooks
-=============================================
+================================================
 
-When building an image only the elements for the preferred configuration methods are required.
+When building an image with `diskimage-builder`_ only the elements for the
-The heat-config element is automatically included as a dependency.
+preferred configuration methods are required. The heat-config element is
+automatically included as a dependency.
 
-An example fedora based image containing some hooks can be built and uploaded to glance
+An example fedora based image containing some hooks can be built and uploaded
-with the following:
+to glance with the following::
-
-::
 
   sudo pip install git+https://git.openstack.org/openstack/diskimage-builder.git
   git clone https://git.openstack.org/openstack/tripleo-image-elements.git
@@ -30,3 +29,5 @@ with the following:
     -o fedora-software-config.qcow2
   openstack image create --disk-format qcow2 --container-format bare fedora-software-config < \
     fedora-software-config.qcow2
+
+.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/

doc/source/install/hooks.rst

@@ -2,23 +2,11 @@
 Available Hooks
 ===============
 
-Below listed are the available hooks.
+The available hooks are:
 
 
 .. toctree::
+   :glob:
    :maxdepth: 1
 
-   hooks/ansible
+   hooks/*
-   hooks/apply-config
-   hooks/cfn-init
-   hooks/chef
-   hooks/docker-cmd
-   hooks/docker-compose
-   hooks/hiera
-   hooks/json-file
-   hooks/kubelet
-   hooks/puppet
-   hooks/salt
-   hooks/script
-
-

doc/source/install/hooks/ansible.rst

@@ -3,6 +3,6 @@ ansible
 =======
 
 A hook which invokes ``ansible-playbook -i "localhost,"`` on the provided
-configuration. Config inputs are written to a 'variables.json' file and
+configuration. Config inputs are written to a ``variables.json`` file and
-then passed to ansible via the '--extra-vars @json_file' parameter.
+then passed to ansible via the ``--extra-vars @json_file`` flag.
 Config output values are read from written-out files.

doc/source/install/hooks/apply-config.rst

@@ -2,17 +2,21 @@
 apply-config
 ============
 
-A hook which invokes os-apply-config.
+A hook which invokes `os-apply-config`_.
 
 The intent is for this element (hook script) to be used in place of the one in
-tripleo-image-elements which relies on an external signal handling
+`tripleo-image-elements`_ which relies on an external signal handling shell
-shell script at the end of the os-refresh-config run (99-refresh-completed).
+script at the end of the `os-refresh-config`_ run (99-refresh-completed). This
-This version will run os-apply-config and return a signal immediately. Because
+version will run `os-apply-config`_ and return a signal immediately. Because it
-it uses the heat-hook mechanisms it also supports a broader set of signal
+uses the heat-hook mechanisms it also supports a broader set of signal handling
-handling capabilities... which 99-refresh-completed doesn't fully support.
+capabilities... which 99-refresh-completed doesn't fully support.
 
 It is worth noting that this hook runs os-apply-config against all the
 accumulated metadata, not just data supplied to an individual hook.
 
-To use this hook set group: to 'apply-config' instead of 'os-apply-config'
+To use this hook set the ``group`` property to `apply-config` instead of
-in your Heat software configuration resources.
+`os-apply-config` in your Heat software configuration resources.
+
+.. _os-apply-config: https://git.openstackorg/cgit/openstack/os-apply-config
+.. _tripleo-image-elements: https://git.openstackorg/cgit/openstack/tripleo-image-elements
+.. _os-refresh-config: https://git.openstackorg/cgit/openstack/os-refresh-config

doc/source/install/hooks/docker-cmd.rst

@@ -2,13 +2,15 @@
 docker-cmd
 ==========
 
-A hook which uses the `docker` command via
+A hook which uses the ``docker`` command via `paunch`_ to deploy containers.
-`paunch <https://docs.openstack.org/developer/paunch/>`_ to deploy containers.
 
 The hook currently supports specifying containers in the `docker-compose v1
-format <https://docs.docker.com/compose/compose-file/#/version-1>`_. The
+format`_. The intention is for this hook to also support the kubernetes pod
-intention is for this hook to also support the kubernetes pod format.
+format.
 
 A dedicated os-refresh-config script will remove running containers if a
 deployment is removed or changed, then the docker-cmd hook will run any
 containers in new or updated deployments.
+
+.. _paunch: https://docs.openstack.org/paunch/latest/
+.. _docker-compose v1 format: https://docs.docker.com/compose/compose-file/#/version-1

doc/source/install/hooks/docker-compose.rst

@@ -2,16 +2,15 @@
 docker-compose
 ==============
 
-A hook which uses `docker-compose` to deploy containers.
+A hook which uses ``docker-compose`` to deploy containers.
 
-A special input 'env_files' can be used with SoftwareConfig and
+A special input ``env_files`` can be used with SoftwareConfig and
-StructuredConfig for docker-compose `env_file` key(s).
+StructuredConfig for docker-compose env_file key(s). If any env_file
+keys specified in ``docker-compose.yml`` do not exist in the ``input_values``
+supplied, docker-compose will throw an error, as it can't find these files.
 
-if env_file keys specified in the `docker-compose.yml`, do not
+Also, the ``--parameter-file`` option can be used to pass env files from the
-exist in input_values supplied, docker-compose will throw an
+client.
-error, as it can't find these files.
-
-Also, `--parameter-file` option can be used to pass env files from client.
 
 Example::
 

doc/source/install/hooks/hiera.rst

@@ -2,9 +2,9 @@
 hiera
 =====
 
-A hook which helps write hiera files to disk and creates
+A hook which helps write `hiera`_ files to disk and creates the ``hiera.yaml``
-the hiera.yaml to order them. This is typically used alongside
+to order them. This is typically used alongside the puppet hook to generate
-of the puppet hook to generate Hiera in a more composable manner.
+Hiera in a more composable manner.
 
 Example::
 
@@ -21,8 +21,10 @@ Example::
               db_connection: foo:/bar
               # customized hiera goes here...
 
-This would write out
+This would write out:
 
-- An /etc/hiera.yaml config file with compute in the hierarchy.
+- An ``/etc/hiera.yaml`` config file with compute in the hierarchy.
-- An /etc/puppet/hieradata/compute.json file loaded with the
+- An ``/etc/puppet/hieradata/compute.json`` file loaded with the
   custom hiera data.
+
+.. _hiera: https://docs.puppet.com/hiera/

doc/source/install/hooks/json-file.rst

@@ -4,7 +4,7 @@ json-file
 
 A hook which helps write JSON files to disk for configuration or use
 with ad-hoc scripts. The data files are written to the named file
-location for each section listed under 'config'.
+location for each section listed under `config`.
 
 Multiple JSON files can be written out in this manner.
 
@@ -19,5 +19,5 @@ Example::
            - bar
            - bar2
 
-This would write out a JSON files at
+This would write out a JSON files at ``/tmp/foo`` containing a JSON
-/tmp/foo containing a JSON representation of ['bar', 'bar2'].
+representation of ``["bar", "bar2"]``.

doc/source/install/hooks/kubelet.rst

@@ -8,19 +8,19 @@ to be provisioned.
 
 The files have the following purpose:
 
-- extra-data.d/50-docker-images allows an archive file of docker images to
+- ``extra-data.d/50-docker-images`` allows an archive file of docker images to
   be included in the dib image
 
-- install.d/50-heat-config-kubelet installs kubernetes for redhat based
+- ``install.d/50-heat-config-kubelet`` installs kubernetes for redhat based
   distros during dib image build, along with the required systemd and config
   files required to enable a working kubelet service on the host
 
-- install.d/hook-kubelet.py polls docker images and containers until the
+- ``install.d/hook-kubelet.py`` polls docker images and containers until the
   expected kubelet-provisioned containers are running (or a timeout occurs)
 
-- os-refresh-config/configure.d/50-heat-config-kubelet runs before
+- ``os-refresh-config/configure.d/50-heat-config-kubelet`` runs before
-  55-heat-config (and the kubelet hook it triggers). This orc script writes
+  ``55-heat-config`` (and the kubelet hook it triggers). This orc script writes
   out all pod definition files for the pods that should currently be running.
-  Kubelet is configured to monitor the directory containing these files, so
+  Kubelet is configured to monitor the directory containing these files, so the
-  the current running containers will change when kubelet acts on these
+  current running containers will change when kubelet acts on these config
-  config changes
+  changes

doc/source/install/hooks/puppet.rst

@@ -10,12 +10,14 @@ are read from written-out files.
 Hook Options
 ------------
 
-- use_facter: default True. Set to True to pass puppet inputs via Facter
+- ``use_facter``: default `True`. Set to True to pass puppet inputs via Facter
-- use_hiera: default False. Set to True to pass puppet inputs via Hiera
+
-- modulepath: If set, puppet will use this filesystem path to load modules
+- ``use_hiera``: default `False`. Set to True to pass puppet inputs via Hiera
-- tags: If set, puppet will use the specified value(s) to apply only a
+- ``modulepath``: If set, puppet will use this filesystem path to load modules
+- ``tags``: If set, puppet will use the specified value(s) to apply only a
   subset of the catalog for a given manifest.
-- enable_debug: default False. Set to True to run puppet apply in debug mode
+- ``enable_debug``: default `False`. Set to True to run puppet apply in debug
-  and have it captured on the node to /var/log/puppet/heat-debug.log
+  mode and have it captured on the node to /var/log/puppet/heat-debug.log
-- enable_verbose: default False. Set to True to run puppet apply in verbose mode
+- ``enable_verbose``: default `False`. Set to True to run puppet apply in
-  and have it captured on the node to /var/log/puppet/heat-verbose.log
+  verbose mode and have it captured on the node to
+  /var/log/puppet/heat-verbose.log

doc/source/install/index.rst

@@ -1,6 +1,6 @@
 ======================
 Installing Heat Agents
-=====================
+======================
 
 .. toctree::
    :maxdepth: 1

tox.ini

@@ -16,7 +16,7 @@ commands = flake8
 
 [testenv:docs]
 deps = -r{toxinidir}/doc/requirements.txt
-commands = python setup.py build_sphinx
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:venv]
 commands = {posargs}