Add tests for documentation (#106)

* Add tests for documentation This is for the 2017 Hackathon napalm-automation/hackathon-2017#10 This commit validates that each Ansible module has a DOCUMENTATION and an EXAMPLES variable. It also asserts that those variables are properly formatted YAML strings. * Add formatting test for EXAMPLES * Fix EXAMPLES variables so they are valid YAML * Generate json files with documentation for modules Content for the RETURN variable will be added later. * Add tests for YAML parsing of RETURN variables * Add tests for content in documentation * Run pytest from Travis * Make pylama happy again * Install napalm_ansible package * Add tests for EXAMPLES and change output format * Documentation fixes * Rename variable * Documentation fixes
napalm-automation · Nov 21, 2017 · 1e36960 · 1e36960
1 parent fbbb70f
commit 1e36960
Show file tree

Hide file tree

Showing 13 changed files with 208 additions and 113 deletions.
diff --git a/.gitignore b/.gitignore
@@ -61,3 +61,5 @@ tags
 *.swp
 
 .compiled
+
+module_docs/
diff --git a/.travis.yml b/.travis.yml
@@ -12,13 +12,16 @@ install:
     - pip install pylama
     - pip install napalm
     - pip install "ansible>=$ANSIBLE_VERSION.0,<$ANSIBLE_VERSION.99"
+    - pip install -r requirements-dev.txt
+    - pip install -e .
 
 script:
     - pylama
     - cd tests
     - ./run_tests.sh
     - ./test_changelog.sh
     - cd ..
+    - py.test
 
 deploy:
   provider: pypi

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,6 +1,7 @@
 develop
 =====
     - Fix old napalm_base references
+    - Various documentation fixes
 
 0.8.0
 =====

diff --git a/napalm_ansible/napalm_cli.py b/napalm_ansible/napalm_cli.py
@@ -12,19 +12,50 @@
 requirements:
     - napalm
 options:
-   args:
+    hostname:
+        description:
+          - IP or FQDN of the device you want to connect to
+        required: False
+    username:
+        description:
+          - Username
+        required: False
+    password:
+        description:
+          - Password
+        required: False
+    args:
         description:
           - Keyword arguments to pass to the `cli` method
         required: True
+    dev_os:
+        description:
+          - OS of the device
+        required: False
+        choices: ['eos', 'junos', 'iosxr', 'fortios', 'ios', 'mock', 'nxos', 'nxos_ssh', 'panos',
+        'vyos']
+    provider:
+        description:
+          - Dictionary which acts as a collection of arguments used to define the characteristics
+            of how to connect to the device.
+            Note - hostname, username, password and dev_os must be defined in either provider
+            or local param
+            Note - local param takes precedence, e.g. hostname is preferred to provider['hostname']
+        required: False
+
 '''
 
 EXAMPLES = '''
-vars:
-  napalm_provider:
+- napalm_cli:
     hostname: "{{ inventory_hostname }}"
     username: "napalm"
     password: "napalm"
     dev_os: "eos"
+    args:
+        commands:
+            - show version
+            - show snmp chassis
+
 - napalm_cli:
     provider: "{{ napalm_provider }}"
     args:
@@ -43,11 +74,10 @@
     description: string of command output
     returned: always
     type: dict
-    sample:
-    {
+    sample: '{
         "show snmp chassis": "Chassis: 1234\n",
         "show version": "Arista vEOS\nHardware version:    \nSerial number:       \nSystem MAC address:  0800.27c3.5f28\n\nSoftware image version: 4.17.5M\nArchitecture:           i386\nInternal build version: 4.17.5M-4414219.4175M\nInternal build ID:      d02143c6-e42b-4fc3-99b6-97063bddb6b8\n\nUptime:                 1 hour and 21 minutes\nTotal memory:           1893416 kB\nFree memory:            956488 kB\n\n"  # noqa
-    }
+    }'
 '''
 
 napalm_found = False

diff --git a/napalm_ansible/napalm_diff_yang.py b/napalm_ansible/napalm_diff_yang.py
@@ -54,20 +54,20 @@
 '''
 
 EXAMPLES = '''
-      napalm_diff_yang:
-        first: "{{ candidate.yang_model }}"
-        second: "{{ running_config.yang_model }}"
-        models:
-            - models.openconfig_interfaces
-      register: diff
+- napalm_diff_yang:
+    first: "{{ candidate.yang_model }}"
+    second: "{{ running_config.yang_model }}"
+    models:
+     - models.openconfig_interfaces
+  register: diff
 '''
 
 RETURN = '''
 diff:
     description: "Same output as the method napalm_yang.utils.diff"
     returned: always
     type: dict
-    sample: {
+    sample: '{
             "interfaces": {
                 "interface": {
                     "both": {
@@ -81,7 +81,7 @@
                         }
                     }
                 }
-            }
+            }'
 '''
 
 

diff --git a/napalm_ansible/napalm_get_facts.py b/napalm_ansible/napalm_get_facts.py
@@ -68,54 +68,47 @@
         default: None
     ignore_notimplemented:
         description:
-          - Ignores NotImplementedError for filters which aren't supported by the driver. Returns
-            invalid filters in a list called: not_implemented
+          - "Ignores NotImplementedError for filters which aren't supported by the driver. Returns
+            invalid filters in a list called: not_implemented"
         required: False
         default: False
         choices: [True, False]
     filter:
         description:
-            - A list of facts to retreive from a device and provided though C(ansible_facts)
+            - "A list of facts to retreive from a device and provided though C(ansible_facts)
               The list of facts available are maintained at:
                   http://napalm.readthedocs.io/en/latest/support/
-              Note- not all getters are implemented on all supported device types
+              Note- not all getters are implemented on all supported device types"
         required: False
         default: ['facts']
     args:
         description:
             - dictionary of kwargs arguments to pass to the filter. The outer key is the name of
               the getter (same as the filter)
-        requited: False
+        required: False
         default: None
 '''
 
 EXAMPLES = '''
-
-vars:
-  ios_provider:
-    hostname: "{{ inventory_hostname }}"
-    username: "napalm"
-    password: "napalm"
-    dev_os: "ios"
-
- - name: get facts from device
-   napalm_get_facts:
-     hostname={{ inventory_hostname }}
-     username={{ user }}
-     dev_os={{ os }}
-     password={{ passwd }}
-     filter=['facts']
-   register: result
-
- - name: print data
-   debug: var=result
-
- - name: Getters
-   napalm_get_facts:
-     provider: "{{ ios_provider }}"
-     filter:
-       - "lldp_neighbors_detail"
-       - "interfaces"
+- name: get facts from device
+  napalm_get_facts:
+    hostname: '{{ inventory_hostname }}'
+    username: '{{ user }}'
+    dev_os: '{{ os }}'
+    password: '{{ passwd }}'
+    filter: ['facts']
+  register: result
+
+- name: print data
+  debug:
+    var: result
+
+- name: Getters
+  napalm_get_facts:
+    provider: "{{ ios_provider }}"
+    filter:
+      - "lldp_neighbors_detail"
+      - "interfaces"
 
 - name: get facts from device
   napalm_get_facts:

diff --git a/napalm_ansible/napalm_install_config.py b/napalm_ansible/napalm_install_config.py
@@ -86,7 +86,6 @@
         description:
           - If set to True, the entire configuration on the device will be replaced during the
             commit. If set to False, we will merge the new config with the existing one.
-            Default: False
         choices: [true,false]
         default: False
         required: False
@@ -113,38 +112,30 @@
 '''
 
 EXAMPLES = '''
-
-vars:
-  ios_provider:
-    hostname: "{{ inventory_hostname }}"
-    username: "napalm"
-    password: "napalm"
-    dev_os: "ios"
-
 - assemble:
-    src=../compiled/{{ inventory_hostname }}/
-    dest=../compiled/{{ inventory_hostname }}/running.conf
-
- - name: Install Config and save diff
-   napalm_install_config:
-    hostname={{ inventory_hostname }}
-    username={{ user }}
-    dev_os={{ os }}
-    password={{ passwd }}
-    config_file=../compiled/{{ inventory_hostname }}/running.conf
-    commit_changes={{ commit_changes }}
-    replace_config={{ replace_config }}
-    get_diffs=True
-    diff_file=../compiled/{{ inventory_hostname }}/diff
-
- - name: Install Config using Provider
-   napalm_install_config:
+    src: '../compiled/{{ inventory_hostname }}/'
+    dest: '../compiled/{{ inventory_hostname }}/running.conf'
+
+- name: Install Config and save diff
+  napalm_install_config:
+    hostname: '{{ inventory_hostname }}'
+    username: '{{ user }}'
+    dev_os: '{{ os }}'
+    password: '{{ passwd }}'
+    config_file: '../compiled/{{ inventory_hostname }}/running.conf'
+    commit_changes: '{{ commit_changes }}'
+    replace_config: '{{ replace_config }}'
+    get_diffs: True
+    diff_file: '../compiled/{{ inventory_hostname }}/diff'
+
+- name: Install Config using Provider
+  napalm_install_config:
     provider: "{{ ios_provider }}"
-    config_file=../compiled/{{ inventory_hostname }}/running.conf
-    commit_changes={{ commit_changes }}
-    replace_config={{ replace_config }}
-    get_diffs=True
-    diff_file=../compiled/{{ inventory_hostname }}/diff
+    config_file: '../compiled/{{ inventory_hostname }}/running.conf'
+    commit_changes: '{{ commit_changes }}'
+    replace_config: '{{ replace_config }}'
+    get_diffs: True
+    diff_file: '../compiled/{{ inventory_hostname }}/diff'
 '''
 
 RETURN = '''

diff --git a/napalm_ansible/napalm_parse_yang.py b/napalm_ansible/napalm_parse_yang.py
@@ -48,7 +48,6 @@
 author: "David Barroso (@dbarrosop)"
 version_added: "0.0"
 short_description: "Parse native config/state from a file or device."
-"YANG obje
 description:
     - "Parse configuration/state from a file or device and returns a dict that"
     - "represents a valid YANG object."
@@ -94,27 +93,37 @@
         default: None
     file_path:
         description:
-          - Path to a file to load native config/state from.
+          - "Path to a file to load native config/state from.
             Note: Either file_path or data to connect to a device must be
               provided.
-            Note: file_path takes precedence over a live device
+            Note: file_path takes precedence over a live device"
         required: False
         defaut: None
     mode:
         description:
-          - Whether to parse config/state or both.
-            Note: `both` is not supported in combination with `file_path`.
+          - "Whether to parse config/state or both.
+            Note: `both` is not supported in combination with `file_path`."
         required: True
         choices: ['config', 'state', 'both']
+    models:
+        description:
+          - A list that should match the SUPPORTED_MODELS in napalm-yang
+        required: True
+        choices: ""
+    profiles:
+        description:
+          - A list profiles
+        required: False
+        choices: ""
 '''
 
 EXAMPLES = '''
 - name: Parse from device
   napalm_parse_yang:
-    hostname={{ inventory_hostname }}
-    username={{ user }}
-    dev_os={{ os }}
-    password={{ passwd }}
+    hostname: '{{ inventory_hostname }}'
+    username: '{{ user }}'
+    dev_os: '{{ os }}'
+    password: '{{ passwd }}'
     mode: "config"
     profiles: ["eos"]
     models:
@@ -133,10 +142,10 @@
 
 RETURN = '''
 changed:
-    description: "Dict the representes a valid YANG object"
-    returned: always
-    type: dict
-    sample: {"interfaces": {"interface": "Et1": {...}, ... }}
+  description: "Dict the representes a valid YANG object"
+  returned: always
+  type: dict
+  sample: "{'interfaces': {'interface':'Et1': {...}, ... }}"
 '''
 
 

diff --git a/napalm_ansible/napalm_ping.py b/napalm_ansible/napalm_ping.py
@@ -87,14 +87,11 @@
 '''
 
 EXAMPLES = '''
-vars:
-  napalm_provider:
+- napalm_ping:
     hostname: "{{ inventory_hostname }}"
     username: "napalm"
     password: "napalm"
     dev_os: "eos"
-- napalm_ping:
-    provider: "{{ napalm_provider }}"
     destination: 10.0.0.5
     vrf: MANAGEMENT
     count: 2
@@ -111,20 +108,24 @@
     returned: always
     type: bool
     sample: True
+
 results:
     description: structure response data of ping
     returned: always
     type: dict
-    sample:
     # when echo request succeeds
-    "{"success": {"packet_loss": 0, "probes_sent": 2,
+    sample: '{"success": {"packet_loss": 0, "probes_sent": 2,
             "results": [{"ip_address": "10.0.0.5:", "rtt": 1.71},
              {"ip_address": "10.0.0.5:", "rtt": 0.733}],
              "rtt_avg": 1.225, "rtt_max": 1.718, "rtt_min": 0.733,
-             "rtt_stddev": 0.493}}
+             "rtt_stddev": 0.493}}'
 
-    # when echo request fails
-    {"error": "connect: Network is unreachable\n"}}
+alt_results:
+    description: Example results key on failure
+    returned: always
+    type: dict
+    # when echo request succeeds
+    sample: '{"error": "connect: Network is unreachable\n"}}'
 '''
 
 napalm_found = False