Browse Source

Clean up heat-agents docs

Improve links, formatting, grammar.

Change-Id: I459b40f30ccd613e19d20e342948f19be1f01efd
Zane Bitter 1 year ago
parent
commit
461013f01c

+ 0
- 8
doc/source/contributor/index.rst View File

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

+ 18
- 33
doc/source/index.rst View File

@@ -1,42 +1,27 @@
1
-.. heat-agents documentation master file, created by
2
-   sphinx-quickstart on Thu Jul 20 08:52:00 2017.
3
-   You can adapt this file completely to your liking, but it should at least
4
-   contain the root `toctree` directive.
1
+Heat Agents
2
+===========
5 3
 
6
-Welcome to Heat Agents!
7
-=======================
4
+Heat Agents are python hooks for deploying software configurations using
5
+`Heat`_.
8 6
 
9
-Overview
10
-========
11 7
 
12
-Heat Agents are python hooks for deploying software configurations using heat.
8
+This repository contains `diskimage-builder`_ elements to build an image with
9
+the software configuration hooks required to use your preferred configuration
10
+method.
13 11
 
12
+These elements depend on some elements found in the `tripleo-image-elements`_
13
+repository. These elements will build an image which uses `os-collect-config`_,
14
+`os-refresh-config`_, and `os-apply-config`_ together to invoke a hook with the
15
+supplied configuration data, and return any outputs back to Heat.
14 16
 
15
-This repository contains `diskimage-builder <https://github.com/openstack/diskimage-builder>`_
16
-elements to build an image with the software configuration hooks
17
-required to use your preferred configuration method.
17
+.. _Heat: https://docs.openstack.org/heat/latest
18
+.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/
19
+.. _tripleo-image-elements: https://git.openstackorg/cgit/openstack/tripleo-image-elements
20
+.. _os-collect-config: https://git.openstackorg/cgit/openstack/os-collect-config
21
+.. _os-refresh-config: https://git.openstackorg/cgit/openstack/os-refresh-config
22
+.. _os-apply-config: https://git.openstackorg/cgit/openstack/os-apply-config
18 23
 
19
-These elements depend on some elements found in the
20
-`tripleo-image-elements <https://github.com/openstack/tripleo-image-elements>`_
21
-repository. These elements will build an image which uses
22
-`os-collect-config <https://github.com/openstack/os-collect-config>`_,
23
-`os-refresh-config <https://github.com/openstack/os-refresh-config>`_, and
24
-`os-apply-config <https://github.com/openstack/os-apply-config>`_ together to
25
-invoke a hook with the supplied configuration data, and return any outputs back
26
-to heat.
27
-
28
-
29
-Index
30
-=====
31 24
 .. toctree::
32
-   :maxdepth: 1
25
+   :maxdepth: 3
33 26
 
34 27
    install/index
35
-   contributor/index
36
-
37
-
38
-Indices and tables
39
-==================
40
-
41
-* :ref:`genindex`
42
-* :ref:`search`

+ 10
- 9
doc/source/install/building_image.rst View File

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

+ 3
- 15
doc/source/install/hooks.rst View File

@@ -2,23 +2,11 @@
2 2
 Available Hooks
3 3
 ===============
4 4
 
5
-Below listed are the available hooks.
5
+The available hooks are:
6 6
 
7 7
 
8 8
 .. toctree::
9
+   :glob:
9 10
    :maxdepth: 1
10 11
 
11
-   hooks/ansible
12
-   hooks/apply-config
13
-   hooks/cfn-init
14
-   hooks/chef
15
-   hooks/docker-cmd
16
-   hooks/docker-compose
17
-   hooks/hiera
18
-   hooks/json-file
19
-   hooks/kubelet
20
-   hooks/puppet
21
-   hooks/salt
22
-   hooks/script
23
-
24
-
12
+   hooks/*

+ 2
- 2
doc/source/install/hooks/ansible.rst View File

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

+ 12
- 8
doc/source/install/hooks/apply-config.rst View File

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

+ 6
- 4
doc/source/install/hooks/docker-cmd.rst View File

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

+ 7
- 8
doc/source/install/hooks/docker-compose.rst View File

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

+ 8
- 6
doc/source/install/hooks/hiera.rst View File

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

+ 3
- 3
doc/source/install/hooks/json-file.rst View File

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

+ 8
- 8
doc/source/install/hooks/kubelet.rst View File

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

+ 10
- 8
doc/source/install/hooks/puppet.rst View File

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

+ 1
- 1
doc/source/install/index.rst View File

@@ -1,6 +1,6 @@
1 1
 ======================
2 2
 Installing Heat Agents
3
-=====================
3
+======================
4 4
 
5 5
 .. toctree::
6 6
    :maxdepth: 1

+ 1
- 1
tox.ini View File

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

Loading…
Cancel
Save