From f7babef5bb8a08e3967e01112bb4795cba7d9bbc Mon Sep 17 00:00:00 2001
From: Nolan Brubaker <nolan.brubaker@rackspace.com>
Date: Thu, 11 Aug 2016 18:17:30 -0400
Subject: [PATCH] Implement inventory API docs

The docstrings for public functions within dynamic_inventory.py are
passed through Sphinx and added to the inventory documentation page.

This change also corrects some of the syntax for the docstrings to fix
warnings and errors.

Change-Id: Ic461b5cff1351111ce3221093f1d6627d2b10aab
---
 doc/source/conf.py                       |  6 ++++--
 doc/source/developer-docs/inventory.rst  |  6 ++++++
 playbooks/inventory/dynamic_inventory.py | 16 ++++++++++------
 3 files changed, 20 insertions(+), 8 deletions(-)

diff --git a/doc/source/conf.py b/doc/source/conf.py
index 9606533d2f..ffd71b3d38 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -26,10 +26,12 @@ import openstackdocstheme
 import os
 import pbr.version
 from subprocess import Popen, PIPE
+import sys
+
 # 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('.'))
+sys.path.insert(0, os.path.abspath('../../playbooks/inventory/'))
 
 # -- General configuration ------------------------------------------------
 
@@ -40,7 +42,7 @@ from subprocess import Popen, PIPE
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 # TODO(ajaeger): enable PDF building, for example add 'rst2pdf.pdfbuilder'
-extensions = []
+extensions = ['sphinx.ext.autodoc']
 
 # Add any paths that contain templates here, relative to this directory.
 #templates_path = ['_templates']
diff --git a/doc/source/developer-docs/inventory.rst b/doc/source/developer-docs/inventory.rst
index a41f1bc57b..7fea9d08fe 100644
--- a/doc/source/developer-docs/inventory.rst
+++ b/doc/source/developer-docs/inventory.rst
@@ -142,6 +142,12 @@ Use the host's name as an argument.
 
 ..  _`dynamic inventory functionality`: http://docs.ansible.com/ansible/intro_dynamic_inventory.html
 
+Dynamic Inventory API documentation
+-----------------------------------
+
+.. automodule:: dynamic_inventory
+   :members:
+
 --------------
 
 .. include:: navigation.txt
diff --git a/playbooks/inventory/dynamic_inventory.py b/playbooks/inventory/dynamic_inventory.py
index d79ea2f0e0..0f5def1325 100755
--- a/playbooks/inventory/dynamic_inventory.py
+++ b/playbooks/inventory/dynamic_inventory.py
@@ -500,7 +500,8 @@ def skel_setup(environment, inventory):
 def skel_load(skeleton, inventory):
     """Build out data as provided from the defined `skel` dictionary.
 
-    :param skeleton:
+    :param skeleton: ``dict`` Dictionary defining group and component
+        memberships for the inventory.
     :param inventory: ``dict``  Living dictionary of inventory
     """
     for key, value in skeleton.iteritems():
@@ -534,10 +535,11 @@ def _add_additional_networks(key, inventory, ip_q, q_name, netmask, interface,
     If the host is found to be "is_metal" it will be marked as "on_metal"
     and will not have an additionally assigned IP address.
 
-    :param key: ``str`` Component key name.
+    :param key: ``str`` Component key name. This could be a group or a host
+        name
     :param inventory: ``dict``  Living dictionary of inventory.
     :param ip_q: ``object`` build queue of IP addresses.
-    :param q_name: ``str`` key to use in host vars for storage.
+    :param q_name: ``str`` key to use in host vars for storage. May be blank.
     :param netmask: ``str`` netmask to use.
     :param interface: ``str`` interface name to set for the network.
     :param user_config: ``dict`` user defined configuration details.
@@ -737,9 +739,11 @@ def find_config_path(user_config_path=None):
     """Return the path to the user configuration files.
 
     If no directory is found the system will exit.
+
     The lookup will be done in the following directories:
-      $(user_config_path)/
-      /etc/openstack_deploy/
+
+      * user_config_path
+      * ``/etc/openstack_deploy/``
 
     :param user_config_path: ``str`` Location to look in FIRST for a file
     """
@@ -993,7 +997,7 @@ def _check_config_settings(cidr_networks, config, container_skel):
 def load_environment(config_path, environment):
     """Create an environment dictionary from config files
 
-    :param config_path: ``str``path where the environment files are kept
+    :param config_path: ``str`` path where the environment files are kept
     :param environment: ``dict`` dictionary to populate with environment data
     """