Add --help-doc subcommand for doc in stdout mode (#225)

Add --help-doc subcommand for doc in stdout mode

Reviewed-by: https://github.com/apps/ansible-zuul

ansible_navigator/actions/doc.py

@@ -90,6 +90,8 @@ def run(self, interaction: Interaction, app: AppPublic) -> Union[Interaction, No
                 except (KeyError, AttributeError, TypeError):
                     self._logger.info("No plugin name found in current content")
                     return None
+            else:
+                return None
         elif plugin_name_source is not C.NOT_SET:
             self._plugin_name = self._args.plugin_name
             self._plugin_type = self._args.plugin_type
@@ -127,6 +129,7 @@ def run_stdout(self) -> None:
         self._run_runner()
 
     def _run_runner(self) -> Union[dict, None]:
+        # pylint: disable=too-many-branches
         """spin up runner"""
 
         plugin_doc_response: Optional[Dict[Any, Any]] = None
@@ -174,7 +177,16 @@ def _run_runner(self) -> Union[dict, None]:
                     return None
                 ansible_doc_path = exec_path
 
-            pass_through_arg = [self._plugin_name, "-t", self._plugin_type]
+            pass_through_arg = []
+            if self._plugin_name is not C.NOT_SET:
+                pass_through_arg.append(self._plugin_name)
+
+            if self._plugin_type is not C.NOT_SET:
+                pass_through_arg.extend(["-t", self._plugin_type])
+
+            if self._args.help_doc is True:
+                pass_through_arg.append("--help")
+
             if isinstance(self._args.cmdline, list):
                 pass_through_arg.extend(self._args.cmdline)
 

ansible_navigator/configuration_subsystem/definitions.py

@@ -22,6 +22,7 @@ class CliParameters(SimpleNamespace):
     nargs: Union[None, Dict] = None
     positional: bool = False
     short: Union[None, str] = None
+    metavar: Union[None, str] = None
 
 
 class Constants(Enum):

ansible_navigator/configuration_subsystem/navigator_configuration.py

@@ -168,6 +168,14 @@ class Internals(SimpleNamespace):
             short_description="Specify the name of the execution environment image",
             value=EntryValue(default="quay.io/ansible/ansible-runner:devel"),
         ),
+        Entry(
+            name="help_doc",
+            choices=[True, False],
+            cli_parameters=CliParameters(short="--hd", action="store_true"),
+            short_description="Help options for ansible-doc command in stdout mode",
+            subcommands=["doc"],
+            value=EntryValue(default=False),
+        ),
         Entry(
             name="inventory",
             cli_parameters=CliParameters(action="append", nargs="+", short="-i"),
@@ -239,7 +247,8 @@ class Internals(SimpleNamespace):
             choices=[True, False],
             cli_parameters=CliParameters(short="--pae"),
             settings_file_path_override="playbook-artifact.enable",
-            short_description="Enable or disable the creation of artifacts for completed playbooks",
+            short_description="Enable or disable the creation of artifacts for"
+            " completed playbooks",
             subcommands=["run"],
             value=EntryValue(default=True),
         ),

ansible_navigator/configuration_subsystem/navigator_post_processor.py

@@ -109,6 +109,17 @@ def execution_environment(self, entry, config) -> PostProcessorReturn:
                 errors.append(error)
         return messages, errors
 
+    @_post_processor
+    def help_doc(self, entry: Entry, config: ApplicationConfiguration) -> PostProcessorReturn:
+        # pylint: disable=unused-argument
+        """Post process help_doc"""
+        messages, errors = self._true_or_false(entry, config)
+        if all((entry.value.current is True, config.app == "doc", config.mode == "interactive")):
+            error = "--help-doc or --hd is valid only when 'mode' argument is set to 'stdout'"
+            errors.append(error)
+            return messages, errors
+        return messages, errors
+
     @staticmethod
     @_post_processor
     def inventory(entry: Entry, config: ApplicationConfiguration) -> PostProcessorReturn:
@@ -232,7 +243,7 @@ def plugin_name(entry: Entry, config: ApplicationConfiguration) -> PostProcessor
         """Post process plugin_name"""
         messages: List[LogMessage] = []
         errors: List[str] = []
-        if config.app == "doc" and entry.value.current is C.NOT_SET:
+        if all((config.app == "doc", entry.value.current is C.NOT_SET, config.help_doc is False)):
             error = "An plugin name is required when using the doc subcommand"
             errors.append(error)
             return messages, errors

ansible_navigator/configuration_subsystem/parser.py

@@ -34,7 +34,6 @@ def generate_argument(entry) -> Tuple[Any, Union[Any, str, None], Dict[str, Any]
         if entry.value.default is not C.NOT_SET:
             kwargs["help"] += f" (default: {entry.value.default})"
         kwargs["default"] = SUPPRESS
-        kwargs["metavar"] = ""
 
         if entry.cli_parameters.positional:
             long = None
@@ -45,9 +44,12 @@ def generate_argument(entry) -> Tuple[Any, Union[Any, str, None], Dict[str, Any]
         else:
             long = entry.cli_parameters.long_override or f"--{entry.name_dashed}"
             kwargs["dest"] = entry.name
-            if entry.cli_parameters.nargs is None:
+            if entry.cli_parameters.nargs is not None:
                 kwargs["nargs"] = entry.cli_parameters.nargs
 
+        if entry.cli_parameters.metavar is not None:
+            kwargs["metavar"] = entry.cli_parameters.metavar
+
         if entry.cli_parameters.action is not None:
             kwargs["action"] = entry.cli_parameters.action
 

docs/settings.rst

@@ -61,6 +61,7 @@ You can copy the example settings file below into one of those paths to start yo
     #         KEY2: VALUE2
     #         KEY3: VALUE3
     #     image: test_image
+    #   help-doc: True
     #   inventories:
     #     - /tmp/test_inventory.yml
     #   inventory-columns:
@@ -159,7 +160,7 @@ The following table describes all available settings.
   * - editor-console
     - Specify if the editor is console based
     - | **Choices:** 'True' or 'False'
-      | **Default:** No default value set
+      | **Default:** True
       | **CLI:** `--econ` or `--editor-console`
       | **ENV:** ANSIBLE_NAVIGATOR_EDITOR_CONSOLE
       | **Settings file:**
@@ -173,7 +174,7 @@ The following table describes all available settings.
   * - execution-environment
     - Enable or disable the use of an execution environment
     - | **Choices:** 'True' or 'False'
-      | **Default:** No default value set
+      | **Default:** True
       | **CLI:** `--ee` or `--execution-environment`
       | **ENV:** ANSIBLE_NAVIGATOR_EXECUTION_ENVIRONMENT
       | **Settings file:**
@@ -289,6 +290,19 @@ The following table describes all available settings.
   * - Name
     - Description
     - Settings
+  * - help-doc
+    - Help options for ansible-doc command in stdout mode
+    - | **Choices:** 'True' or 'False'
+      | **Default:** False
+      | **CLI:** `--hd` or `--help-doc`
+      | **ENV:** ANSIBLE_NAVIGATOR_HELP_DOC
+      | **Settings file:**
+
+      .. code-block:: yaml
+
+            ansible-navigator:
+              help-doc:
+
   * - plugin-name
     - Specify the plugin name
     - | **Default:** No default value set
@@ -424,7 +438,7 @@ The following table describes all available settings.
   * - playbook-artifact-enable
     - Enable or disable the creation of artifacts for completed playbooks
     - | **Choices:** 'True' or 'False'
-      | **Default:** No default value set
+      | **Default:** True
       | **CLI:** `--pae` or `--playbook-artifact-enable`
       | **ENV:** ANSIBLE_NAVIGATOR_PLAYBOOK_ARTIFACT_ENABLE
       | **Settings file:**

tests/fixtures/integration/actions/doc/test_stdout.py/test/lookup_doc_with_ee/0.json

@@ -0,0 +1,53 @@
+{
+    "name": "test[0-ansible-navigator doc testorg.coll_1.lookup_1 -t lookup -m stdout -j --execution-environment true --ce podman-ansible-navigator lookup doc in stdout mode with EE-lookup_doc_with_ee-None]",
+    "index": 0,
+    "comment": "ansible-navigator lookup doc in stdout mode with EE",
+    "output": [
+        "{",
+        "    \"testorg.coll_1.lookup_1\": {",
+        "        \"doc\": {",
+        "            \"author\": \"test\",",
+        "            \"collection\": \"testorg.coll_1\",",
+        "            \"description\": [",
+        "                \"This is test lookup plugin\"",
+        "            ],",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+        "            \"name\": \"lookup_1\",",
+        "            \"notes\": [",
+        "                \"This is a dummy lookup plugin\"",
+        "            ],",
+        "            \"options\": {",
+        "                \"bar\": {",
+        "                    \"default\": \"candidate\",",
+        "                    \"description\": [",
+        "                        \"Dummy option I(bar)\"",
+        "                    ],",
+        "                    \"type\": \"str\"",
+        "                },",
+        "                \"foo\": {",
+        "                    \"description\": [",
+        "                        \"Dummy option I(foo)\"",
+        "                    ],",
+        "                    \"required\": true,",
+        "                    \"type\": \"str\"",
+        "                }",
+        "            },",
+        "            \"plugin_type\": \"lookup\",",
+        "            \"short_description\": \"This is test lookup plugin\",",
+        "            \"version_added\": \"1.0.0\",",
+        "            \"version_added_collection\": \"testorg.coll_1\"",
+        "        },",
+        "        \"examples\": \"\\n    - name: Retrieve a value deep inside a using a path\\n      ansible.builtin.set_fact:\\n        value: \\\"{{ lookup('testorg.coll_1.lookup_1', var1, var2) }}\\\"\\n    \",",
+        "        \"metadata\": null,",
+        "        \"return\": {",
+        "            \"_raw\": {",
+        "                \"description\": [",
+        "                    \"One or more zero-based indices of the matching list items.\"",
+        "                ]",
+        "            }",
+        "        }",
+        "    }",
+        "}",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+    ]
+}

tests/fixtures/integration/actions/doc/test_stdout.py/test/lookup_doc_without_ee/0.json

@@ -0,0 +1,53 @@
+{
+    "name": "test[0-ansible-navigator doc testorg.coll_1.lookup_1 -t lookup -m stdout -j --execution-environment false-ansible-navigator lookup doc in stdout mode without EE-lookup_doc_without_ee-None]",
+    "index": 0,
+    "comment": "ansible-navigator lookup doc in stdout mode without EE",
+    "output": [
+        "{",
+        "    \"testorg.coll_1.lookup_1\": {",
+        "        \"doc\": {",
+        "            \"author\": \"test\",",
+        "            \"collection\": \"testorg.coll_1\",",
+        "            \"description\": [",
+        "                \"This is test lookup plugin\"",
+        "            ],",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+        "            \"name\": \"lookup_1\",",
+        "            \"notes\": [",
+        "                \"This is a dummy lookup plugin\"",
+        "            ],",
+        "            \"options\": {",
+        "                \"bar\": {",
+        "                    \"default\": \"candidate\",",
+        "                    \"description\": [",
+        "                        \"Dummy option I(bar)\"",
+        "                    ],",
+        "                    \"type\": \"str\"",
+        "                },",
+        "                \"foo\": {",
+        "                    \"description\": [",
+        "                        \"Dummy option I(foo)\"",
+        "                    ],",
+        "                    \"required\": true,",
+        "                    \"type\": \"str\"",
+        "                }",
+        "            },",
+        "            \"plugin_type\": \"lookup\",",
+        "            \"short_description\": \"This is test lookup plugin\",",
+        "            \"version_added\": \"1.0.0\",",
+        "            \"version_added_collection\": \"testorg.coll_1\"",
+        "        },",
+        "        \"examples\": \"\\n    - name: Retrieve a value deep inside a using a path\\n      ansible.builtin.set_fact:\\n        value: \\\"{{ lookup('testorg.coll_1.lookup_1', var1, var2) }}\\\"\\n    \",",
+        "        \"metadata\": null,",
+        "        \"return\": {",
+        "            \"_raw\": {",
+        "                \"description\": [",
+        "                    \"One or more zero-based indices of the matching list items.\"",
+        "                ]",
+        "            }",
+        "        }",
+        "    }",
+        "}",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+    ]
+}

tests/fixtures/integration/actions/doc/test_stdout.py/test/module_doc_with_ee/0.json

@@ -0,0 +1,65 @@
+{
+    "name": "test[0-ansible-navigator doc testorg.coll_1.mod_1 -m stdout -j --execution-environment true --ce podman-ansible-navigator doc in stdout mode with EE-module_doc_with_ee-None]",
+    "index": 0,
+    "comment": "ansible-navigator doc in stdout mode with EE",
+    "output": [
+        "{",
+        "    \"testorg.coll_1.mod_1\": {",
+        "        \"doc\": {",
+        "            \"author\": [",
+        "                \"test\"",
+        "            ],",
+        "            \"collection\": \"testorg.coll_1\",",
+        "            \"description\": [",
+        "                \"This is a test module\"",
+        "            ],",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+        "            \"has_action\": false,",
+        "            \"module\": \"mod_1\",",
+        "            \"notes\": [",
+        "                \"This is a dummy module\"",
+        "            ],",
+        "            \"options\": {",
+        "                \"bar\": {",
+        "                    \"aliases\": [",
+        "                        \"bam\"",
+        "                    ],",
+        "                    \"choices\": [",
+        "                        \"candidate\",",
+        "                        \"running\"",
+        "                    ],",
+        "                    \"default\": \"candidate\",",
+        "                    \"description\": [",
+        "                        \"Dummy option I(bar)\"",
+        "                    ],",
+        "                    \"type\": \"str\"",
+        "                },",
+        "                \"foo\": {",
+        "                    \"description\": [",
+        "                        \"Dummy option I(foo)\"",
+        "                    ],",
+        "                    \"type\": \"str\"",
+        "                }",
+        "            },",
+        "            \"short_description\": \"This is a test module\",",
+        "            \"version_added\": \"1.0.0\",",
+        "            \"version_added_collection\": \"testorg.coll_1\"",
+        "        },",
+        "        \"examples\": \"\\n- name: test task-1\\n  testorg.coll_1.mod_1:\\n    foo: somevalue\\n    bar: candidate\\n\",",
+        "        \"metadata\": null,",
+        "        \"return\": {",
+        "            \"baz\": {",
+        "                \"description\": \"test return 1\",",
+        "                \"returned\": \"success\",",
+        "                \"sample\": [",
+        "                    \"a\",",
+        "                    \"b\"",
+        "                ],",
+        "                \"type\": \"list\"",
+        "            }",
+        "        }",
+        "    }",
+        "}",
+        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+    ]
+}