From f7babef5bb8a08e3967e01112bb4795cba7d9bbc Mon Sep 17 00:00:00 2001 From: Nolan Brubaker 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 """