From 53ac312382c4ecf27b0d85a06bc86034a3b7fa50 Mon Sep 17 00:00:00 2001
From: John R Barker <john@johnrbarker.com>
Date: Wed, 15 Feb 2017 08:09:08 +0000
Subject: [PATCH] validate-modules --arg-spec (#21331)

* validate-modules --arg-spec

* Update developing_modules_documenting.rst

* Never mock out ansible or ansible.module_utils

* No more false positives
---
 .../dev_guide/developing_modules_documenting.rst  | 15 ++++++++++++---
 test/sanity/validate-modules/module_args.py       |  4 ++++
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
index 83d6ff13723..fed5679e3bc 100644
--- a/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
+++ b/docs/docsite/rst/dev_guide/developing_modules_documenting.rst
@@ -41,6 +41,7 @@ The following fields can be used and are all required unless specified otherwise
   * As the short description is displayed by ``ansible-doc -l`` without the category grouping it needs enough detail to explain its purpose without the context of the directory structure in which it lives.
   * Unlike ``description:`` this field should not have a trailing full stop.
 * ``description:``
+
   * A detailed description (generally two or more sentences).
   * Must be written in full sentences, i.e. with capital letters and fullstops.
   * Shouldn't mention the name module.
@@ -62,10 +63,10 @@ The following fields can be used and are all required unless specified otherwise
   * ``required:``
     Only needed if true, otherwise it is assumed to be false.
   * ``default:``
-  
+
     * If `required` is false/missing, `default` may be specified (assumed 'null' if missing).
-    * Ensure that the default parameter in the docs matches the default parameter in the code. 
-    * The default option must not be listed as part of the description. 
+    * Ensure that the default parameter in the docs matches the default parameter in the code.
+    * The default option must not be listed as part of the description.
   * ``choices:``
     List of option values. Should be absent if empty.
   * ``aliases:``
@@ -173,6 +174,14 @@ Put your completed module file into the ``lib/ansible/modules/$CATEGORY/`` direc
 run the command: ``make webdocs``. The new 'modules.html' file will be
 built in the ``docs/docsite/_build/html/$MODULENAME_module.html`` directory.
 
+To test your documentation against your ``argument_spec`` you can use ``validate-modules``. Note that this option isn't currently enabled in Shippable due to the time it takes to run.
+
+.. code-block:: shell-session
+
+   # If you don't already, ensure you are using your local checkout
+   $ source hacking/env-setup
+   $ ./test/sanity/validate-modules/validate-modules --arg-spec --warnings  lib/ansible/modules/your/modules/
+
 .. tip::
 
    If you're having a problem with the syntax of your YAML you can
diff --git a/test/sanity/validate-modules/module_args.py b/test/sanity/validate-modules/module_args.py
index 07f3f82a484..473e69d42f8 100644
--- a/test/sanity/validate-modules/module_args.py
+++ b/test/sanity/validate-modules/module_args.py
@@ -71,6 +71,10 @@ def add_mocks(filename):
             parts = module.split('.')
             for i in range(len(parts)):
                 dotted = '.'.join(parts[:i+1])
+                # Never mock out ansible or ansible.module_utils
+                # we may get here if a specific module_utils file needed mocked
+                if dotted in ('ansible', 'ansible.module_utils',):
+                    continue
                 sys.modules[dotted] = sys_mock
                 sys_mocks.append(dotted)