Use attributes to document module capabilities; warn about command module's check_mode support (#118)

* Improve formatting.

* Add 'api' action group attribute.

* Document attributes.

* Known issue: command module declares to support check mode.

* Compatibility with older ansible-core releases.

* Fix typo.

* Improve docs.

* Add shortcuts for common combinations.

* Update changelogs/fragments/command-check_mode.yml

Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>

Co-authored-by: Brian Scholer <1260690+briantist@users.noreply.github.com>

changelogs/fragments/command-check_mode.yml

@@ -0,0 +1,4 @@
+known_issues:
+  - "The ``community.routeros.command`` module claims to support check mode.
+     Since it cannot judge whether the commands executed modify state or not, this behavior is incorrect.
+     Since this potentially breaks existing playbooks, we will not change this behavior until community.routeros 3.0.0."

docs/docsite/rst/api-guide.rst

@@ -17,7 +17,7 @@ No special setup is needed; the module needs to be run on a host that can connec
     ---
     - name: RouterOS test with API
       hosts: localhost
-      gather_facts: no
+      gather_facts: false
       vars:
         hostname: 192.168.1.1
         username: admin
@@ -71,7 +71,7 @@ To avoid having to specify common parameters for all the API based modules in ev
     ---
     - name: RouterOS test with API
       hosts: localhost
-      gather_facts: no
+      gather_facts: false
       module_defaults:
         group/community.routeros.api
           hostname: 192.168.1.1

meta/runtime.yml

@@ -6,8 +6,8 @@
 requires_ansible: '>=2.9.10'
 action_groups:
   api:
-  - api
+    - api
-  - api_facts
+    - api_facts
-  - api_find_and_modify
+    - api_find_and_modify
-  - api_info
+    - api_info
-  - api_modify
+    - api_modify

plugins/doc_fragments/attributes.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+
+# Copyright (c) Ansible Project
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import (absolute_import, division, print_function)
+__metaclass__ = type
+
+
+class ModuleDocFragment(object):
+
+    # Standard documentation fragment
+    DOCUMENTATION = r'''
+options: {}
+attributes:
+    check_mode:
+      description: Can run in C(check_mode) and return changed status prediction without modifying target.
+    diff_mode:
+      description: Will return details on what has changed (or possibly needs changing in C(check_mode)), when in diff mode.
+    platform:
+      description: Target OS/families that can be operated against.
+      support: N/A
+'''
+
+    # Should be used together with the standard fragment
+    INFO_MODULE = r'''
+options: {}
+attributes:
+    check_mode:
+      support: full
+      details:
+        - This action does not modify state.
+    diff_mode:
+      support: N/A
+      details:
+        - This action does not modify state.
+'''
+
+    ACTIONGROUP_API = r'''
+options: {}
+attributes:
+    action_group:
+      description: Use C(group/community.routeros.api) in C(module_defaults) to set defaults for this module.
+      support: full
+      membership:
+        - community.routeros.api
+'''
+
+    CONN = r'''
+options: {}
+attributes:
+    become:
+      description: Is usable alongside C(become) keywords.
+    connection:
+      description: Uses the target's configured connection information to execute code on it.
+    delegation:
+      description: Can be used in conjunction with C(delegate_to) and related keywords.
+'''
+
+    FACTS = r'''
+options: {}
+attributes:
+    facts:
+      description: Action returns an C(ansible_facts) dictionary that will update existing host facts.
+'''
+
+    # Should be used together with the standard fragment and the FACTS fragment
+    FACTS_MODULE = r'''
+options: {}
+attributes:
+    check_mode:
+      support: full
+      details:
+        - This action does not modify state.
+    diff_mode:
+      support: N/A
+      details:
+        - This action does not modify state.
+    facts:
+      support: full
+'''
+
+    FILES = r'''
+options: {}
+attributes:
+    safe_file_operations:
+      description: Uses Ansible's strict file operation functions to ensure proper permissions and avoid data corruption.
+'''
+
+    FLOW = r'''
+options: {}
+attributes:
+    action:
+      description: Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller.
+    async:
+      description: Supports being used with the C(async) keyword.
+'''

plugins/modules/api.py

@@ -18,12 +18,23 @@ description:
   - This module can add, remove, update, query and execute arbitrary command in RouterOS via API.
 notes:
   - I(add), I(remove), I(update), I(cmd) and I(query) are mutually exclusive.
-  - I(check_mode) is not supported.
   - Use the M(community.routeros.api_modify) and M(community.routeros.api_find_and_modify) modules
     for more specific modifications, and the M(community.routeros.api_info) module for a more controlled
     way of returning all entries for a path.
 extends_documentation_fragment:
   - community.routeros.api
+  - community.routeros.attributes
+  - community.routeros.attributes.actiongroup_api
+attributes:
+  check_mode:
+    support: none
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: RouterOS
+  action_group:
+    version_added: 2.1.0
 options:
   path:
     description:

plugins/modules/api_facts.py

@@ -28,6 +28,14 @@ description:
     RouterOS API, similar to the M(community.routeros.api) module.
 extends_documentation_fragment:
   - community.routeros.api
+  - community.routeros.attributes
+  - community.routeros.attributes.actiongroup_api
+  - community.routeros.attributes.facts
+  - community.routeros.attributes.facts_module
+attributes:
+  platform:
+    support: full
+    platforms: RouterOS
 options:
   gather_subset:
     description:

plugins/modules/api_find_and_modify.py

@@ -24,9 +24,18 @@ notes:
      there are at least N such values, you can use I(require_matches_min=N) together with I(allow_no_matches=true).
      This will make the module fail if there are less than N such entries, but not if there is no match. The latter case
      is needed for idempotency of the task: once the values have been changed, there should be no further match."
-  - Supports I(check_mode).
 extends_documentation_fragment:
   - community.routeros.api
+  - community.routeros.attributes
+  - community.routeros.attributes.actiongroup_api
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: full
+  platform:
+    support: full
+    platforms: RouterOS
 options:
   path:
     description:

plugins/modules/api_info.py

@@ -24,10 +24,15 @@ description:
   - B(Note) that this module is still heavily in development, and only supports B(some) paths.
     If you want to support new paths, or think you found problems with existing paths, please first
     L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/).
-notes:
-  - Supports I(check_mode).
 extends_documentation_fragment:
   - community.routeros.api
+  - community.routeros.attributes
+  - community.routeros.attributes.actiongroup_api
+  - community.routeros.attributes.info_module
+attributes:
+  platform:
+    support: full
+    platforms: RouterOS
 options:
   path:
     description:

plugins/modules/api_modify.py

@@ -24,12 +24,20 @@ description:
   - B(Note) that this module is still heavily in development, and only supports B(some) paths.
     If you want to support new paths, or think you found problems with existing paths, please first
     L(create an issue in the community.routeros Issue Tracker,https://github.com/ansible-collections/community.routeros/issues/).
-notes:
-  - Supports I(check_mode).
 requirements:
   - Needs L(ordereddict,https://pypi.org/project/ordereddict) for Python 2.6
 extends_documentation_fragment:
   - community.routeros.api
+  - community.routeros.attributes
+  - community.routeros.attributes.actiongroup_api
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: full
+  platform:
+    support: full
+    platforms: RouterOS
 options:
   path:
     description:

plugins/modules/command.py

@@ -20,6 +20,21 @@ description:
   - The module always indicates a (changed) status. You can use
     R(the changed_when task property,override_the_changed_result) to determine
     whether a command task actually resulted in a change or not.
+notes:
+  - The module declares that it B(supports check mode). This is a bug and will
+    be changed in community.routeros 3.0.0.
+extends_documentation_fragment:
+  - community.routeros.attributes
+attributes:
+  check_mode:
+    support: partial
+    details:
+      - The module claims to support check mode, but it simply always executes the command.
+  diff_mode:
+    support: none
+  platform:
+    support: full
+    platforms: RouterOS
 options:
   commands:
     description:

plugins/modules/facts.py

@@ -18,6 +18,14 @@ description:
     base network fact keys with C(ansible_net_<fact>).  The facts
     module will always collect a base set of facts from the device
     and can enable or disable collection of additional facts.
+extends_documentation_fragment:
+  - community.routeros.attributes
+  - community.routeros.attributes.facts
+  - community.routeros.attributes.facts_module
+attributes:
+  platform:
+    support: full
+    platforms: RouterOS
 options:
   gather_subset:
     description: