Add code to build documentation for napalm-ansible (#535)

* Add code to build documentation for napalm-ansible

* pep8

* Change placement in documentation tree

* Change formatting

* Fix formatting for return values

* Sort parameters alphabetically

* Text changes

* Add script to clone napalm-ansible repo

.gitignore

@@ -63,3 +63,7 @@ test/unit/test_devices.py
 
 report.json
 tags
+
+docs/integrations/ansible/modules/napalm_*/
+docs/integrations/ansible/modules/source/*.json
+docs/napalm_ansible_repo/

docs/ansible-module.j2

@@ -0,0 +1,64 @@
+{{ name }}
+=====================
+
+{{ doc['description'][0] }}
+
+
+Parameters
+----------
+
+.. raw:: html
+
+	<table border="1" class="docutils">
+		<th>Parameter</th>
+		<th>Required</th>
+		<th>Default</th>
+		<th>Choices</th>
+		<th>Description</th>
+	{% for p in doc['options']|sort %}
+			<tr>
+				<td>{{ p }}</td>
+				<td>{{ doc['options'][p]['required'] }}</td>
+				<td>N/A</td>
+				<td>N/A</td>
+				<td>{{ doc['options'][p]['description'][0] }}</td>
+			</tr>
+	{% endfor %}
+
+	</table>
+
+
+Examples
+--------
+
+.. code-block:: yaml
+
+	{% for line in example_lines %}
+	{{ line }}
+	{% endfor %}
+
+{% if return_values %}
+
+Return
+------
+.. raw:: html
+
+	<table border="1" class="docutils">
+		<th>Name</th>
+		<th>Description</th>
+		<th>Returned</th>
+		<th>Type</th>
+		<th>Sample</th>
+	{% for value in return_values %}
+			<tr>
+				<td>{{ value }}</td>
+				<td>{{ return_values[value].description }}</td>
+				<td>{{ return_values[value].returned }}</td>
+				<td>{{ return_values[value].type }}</td>
+				<td>{{ return_values[value].sample|replace('\n', '\\n') }}</td>
+			</tr>
+	{% endfor %}
+	</table>
+
+
+{% endif %}

docs/build-ansible-module-docs.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+CWD=`pwd`
+MODULES_OUTPUT="$CWD/integrations/ansible/modules/source"
+
+
+
+git clone https://github.com/napalm-automation/napalm-ansible.git napalm_ansible_repo
+cd napalm_ansible_repo
+
+# Change to master after next napalm-ansible release
+git checkout develop
+
+pip install -r requirements-dev.txt
+pip install .
+py.test
+cp module_docs/* $MODULES_OUTPUT/
+
+cd $CWD
+

docs/conf.py

@@ -20,7 +20,7 @@
 import subprocess
 import sys
 
-
+from glob import glob
 from napalm.base import NetworkDriver
 from jinja2 import Environment, FileSystemLoader
 
@@ -81,7 +81,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', 'napalm_ansible_repo']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -306,6 +306,40 @@ def _merge_results(last, intermediate):
         return last
 
 
+def build_napalm_ansible_module_docs(app):
+    """Create documentation for Ansible modules."""
+
+    # Add script to clone napalm-ansible repo
+    status = subprocess.call("./build-ansible-module-docs.sh", stdout=sys.stdout, stderr=sys.stderr)
+
+    if status != 0:
+        print("Something bad happened when processing the Ansible modules.")
+        sys.exit(-1)
+
+    env = Environment(loader=FileSystemLoader("."))
+
+    modules_dir = './integrations/ansible/modules/source'
+    module_files = glob('{0}/*.json'.format(modules_dir))
+    for module_file in module_files:
+        with open(module_file, 'r') as f:
+            module = module_file.split('/')[-1].split('.')[0]
+            data = json.loads(f.read())
+            data['name'] = module
+
+        module_dir = './integrations/ansible/modules/{0}'.format(module)
+
+        try:
+            os.stat(module_dir)
+        except Exception:
+            os.mkdir(module_dir)
+
+        template_file = env.get_template("ansible-module.j2")
+        rendered_template = template_file.render(**data)
+
+        with open('{0}/index.rst'.format(module_dir), 'w') as f:
+            f.write(rendered_template)
+
+
 def build_getters_support_matrix(app):
     """Build the getters support matrix."""
     status = subprocess.call("./test.sh", stdout=sys.stdout, stderr=sys.stderr)
@@ -356,6 +390,8 @@ def build_getters_support_matrix(app):
 def setup(app):
     """Map methods to states of the documentation build."""
     app.connect('builder-inited', build_getters_support_matrix)
+    app.connect('builder-inited', build_napalm_ansible_module_docs)
 
 
 build_getters_support_matrix(None)
+build_napalm_ansible_module_docs(None)

docs/index.rst

@@ -60,6 +60,7 @@ Documentation
    base
    yang
    logs
+   integrations/index
    contributing/index
    development/index
    hackathons/index

docs/integrations/ansible/index.rst

@@ -0,0 +1,9 @@
+napalm-ansible
+==============
+
+Below are the ansible modules which are currently available for NAPALM
+
+.. toctree::
+   :maxdepth: 1
+
+   modules/index

docs/integrations/ansible/modules/index.rst

@@ -0,0 +1,10 @@
+modules
+=======
+
+Below are the ansible modules which are currently available for NAPALM
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   napalm_*/index

docs/integrations/index.rst

@@ -0,0 +1,9 @@
+Integrations
+============
+
+NAPALM can be integrated with automation frameworks such as Ansible or Salt. In order to use NAPALM with ansible you will need to install napalm-ansible.
+
+.. toctree::
+   :maxdepth: 1
+
+   ansible/index