Merge pull request #74 from vera-chan/link-fix

update/fix links, minor editorial changes to filter doc

Author: stewartfrancis

docs/source/community_guides.rst

@@ -20,7 +20,7 @@ For a developer guide on how to develop and run test cases for IBM® z/OS® CICS
 .. _git issues:
    https://github.com/ansible-collections/ibm_zos_cics/issues
 .. _Developer guide:
-   https://github.com/ansible-collections/ibm_zos_cics/tree/master/CONTRIBUTING.md
+   https://github.com/ansible-collections/ibm_zos_cics/blob/main/devguide.md
 
 
 

docs/source/modules/cmci_action.rst

@@ -189,9 +189,9 @@ resources
 
     Filters can be nested. At most four nesting layers are allowed.
 
-    When supplying the ``attribute`` option, you must also supply a ``value`` for the filter.  You can also override the default operator of ``=`` with the ``operator`` option.
+    When supplying the ``attribute`` option, you must also supply a ``value`` for the filter. You can also override the default operator of ``=`` with the ``operator`` option.
 
-    For examples, see :ref:`cmci_get <cmci_get_module>`
+    For examples, see "Examples" in :ref:`cmci_get <cmci_get_module>`.
 
 
     | **required**: False
@@ -202,7 +202,7 @@ resources
     and
       A list of filter expressions to be combined with an ``and`` operation.
 
-      Filter expressions are nested ``complex_filter`` elements.  Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
+      Filter expressions are nested ``complex_filter`` elements. Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
 
 
       | **required**: False
@@ -222,7 +222,7 @@ resources
 
 
     operator
-      These operators are accepted: ``<`` or ``LT`` (less than), ``<=`` or ``LE`` (less than or equal to), ``=`` or ``EQ`` (equal to), ``>`` or ``GT`` (greater than), ``>=`` or ``GE`` (greater than or equal to), ``==`` or ``IS`` (is), ``¬=``, ``!=``, or ``NE`` (not equal to).  If not supplied when 'attribute' is used, ``EQ`` will be assumed.
+      These operators are accepted: ``<`` or ``LT`` (less than), ``<=`` or ``LE`` (less than or equal to), ``=`` or ``EQ`` (equal to), ``>`` or ``GT`` (greater than), ``>=`` or ``GE`` (greater than or equal to), ``==`` or ``IS`` (is), ``¬=``, ``!=``, or ``NE`` (not equal to). If not supplied when ``attribute`` is used, ``EQ`` is assumed.
 
 
 
@@ -235,7 +235,7 @@ resources
     or
       A list of filter expressions to be combined with an ``or`` operation.
 
-      Filter expressions are nested ``complex_filter`` elements.  Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
+      Filter expressions are nested ``complex_filter`` elements. Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
 
 
       | **required**: False
@@ -258,17 +258,17 @@ resources
   filter
     A dictionary with attribute names as keys, and target values, to be used as criteria to filter the set of resources returned from CICSPlex SM.
 
-    Filters implicitly use the ``=`` operator
+    Filters implicitly use the ``=`` operator.
 
-    Filters for ``string`` type attributes can use the ``*`` and ``+`` wildcard operators
+    Filters for ``string`` type attributes can use the ``*`` and ``+`` wildcard operators.
 
-    ``*`` is a wildcard representing an unknown number of characters, and must appear at the end of the value
+    ``*`` is a wildcard representing an unknown number of characters, and must appear at the end of the value.
 
     ``+`` is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times.
 
     To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with ``and`` and ``or`` operators, see the ``complex_filter`` parameter.
 
-    For examples, see :ref:`cmci_get <cmci_get_module>`
+    For examples, see "Examples" in :ref:`cmci_get <cmci_get_module>`.
 
     For more details, see `How to build a filter expression <https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/system-programming/cpsm/eyup1a0.html>`_.
 

docs/source/modules/cmci_delete.rst

@@ -149,9 +149,9 @@ resources
 
     Filters can be nested. At most four nesting layers are allowed.
 
-    When supplying the ``attribute`` option, you must also supply a ``value`` for the filter.  You can also override the default operator of ``=`` with the ``operator`` option.
+    When supplying the ``attribute`` option, you must also supply a ``value`` for the filter. You can also override the default operator of ``=`` with the ``operator`` option.
 
-    For examples, see :ref:`cmci_get <cmci_get_module>`
+    For examples, see "Examples" in :ref:`cmci_get <cmci_get_module>`.
 
 
     | **required**: False
@@ -162,7 +162,7 @@ resources
     and
       A list of filter expressions to be combined with an ``and`` operation.
 
-      Filter expressions are nested ``complex_filter`` elements.  Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
+      Filter expressions are nested ``complex_filter`` elements. Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
 
 
       | **required**: False
@@ -182,7 +182,7 @@ resources
 
 
     operator
-      These operators are accepted: ``<`` or ``LT`` (less than), ``<=`` or ``LE`` (less than or equal to), ``=`` or ``EQ`` (equal to), ``>`` or ``GT`` (greater than), ``>=`` or ``GE`` (greater than or equal to), ``==`` or ``IS`` (is), ``¬=``, ``!=``, or ``NE`` (not equal to).  If not supplied when 'attribute' is used, ``EQ`` will be assumed.
+      These operators are accepted: ``<`` or ``LT`` (less than), ``<=`` or ``LE`` (less than or equal to), ``=`` or ``EQ`` (equal to), ``>`` or ``GT`` (greater than), ``>=`` or ``GE`` (greater than or equal to), ``==`` or ``IS`` (is), ``¬=``, ``!=``, or ``NE`` (not equal to). If not supplied when ``attribute`` is used, ``EQ`` is assumed.
 
 
 
@@ -195,7 +195,7 @@ resources
     or
       A list of filter expressions to be combined with an ``or`` operation.
 
-      Filter expressions are nested ``complex_filter`` elements.  Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
+      Filter expressions are nested ``complex_filter`` elements. Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
 
 
       | **required**: False
@@ -218,17 +218,17 @@ resources
   filter
     A dictionary with attribute names as keys, and target values, to be used as criteria to filter the set of resources returned from CICSPlex SM.
 
-    Filters implicitly use the ``=`` operator
+    Filters implicitly use the ``=`` operator.
 
-    Filters for ``string`` type attributes can use the ``*`` and ``+`` wildcard operators
+    Filters for ``string`` type attributes can use the ``*`` and ``+`` wildcard operators.
 
-    ``*`` is a wildcard representing an unknown number of characters, and must appear at the end of the value
+    ``*`` is a wildcard representing an unknown number of characters, and must appear at the end of the value.
 
     ``+`` is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times.
 
     To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with ``and`` and ``or`` operators, see the ``complex_filter`` parameter.
 
-    For examples, see :ref:`cmci_get <cmci_get_module>`
+    For examples, see "Examples" in :ref:`cmci_get <cmci_get_module>`.
 
     For more details, see `How to build a filter expression <https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/system-programming/cpsm/eyup1a0.html>`_.
 

docs/source/modules/cmci_get.rst

@@ -162,9 +162,9 @@ resources
 
     Filters can be nested. At most four nesting layers are allowed.
 
-    When supplying the ``attribute`` option, you must also supply a ``value`` for the filter.  You can also override the default operator of ``=`` with the ``operator`` option.
+    When supplying the ``attribute`` option, you must also supply a ``value`` for the filter. You can also override the default operator of ``=`` with the ``operator`` option.
 
-    For examples, see :ref:`cmci_get <cmci_get_module>`
+    For examples, see "Examples" in :ref:`cmci_get <cmci_get_module>`.
 
 
     | **required**: False
@@ -175,7 +175,7 @@ resources
     and
       A list of filter expressions to be combined with an ``and`` operation.
 
-      Filter expressions are nested ``complex_filter`` elements.  Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
+      Filter expressions are nested ``complex_filter`` elements. Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
 
 
       | **required**: False
@@ -195,7 +195,7 @@ resources
 
 
     operator
-      These operators are accepted: ``<`` or ``LT`` (less than), ``<=`` or ``LE`` (less than or equal to), ``=`` or ``EQ`` (equal to), ``>`` or ``GT`` (greater than), ``>=`` or ``GE`` (greater than or equal to), ``==`` or ``IS`` (is), ``¬=``, ``!=``, or ``NE`` (not equal to).  If not supplied when 'attribute' is used, ``EQ`` will be assumed.
+      These operators are accepted: ``<`` or ``LT`` (less than), ``<=`` or ``LE`` (less than or equal to), ``=`` or ``EQ`` (equal to), ``>`` or ``GT`` (greater than), ``>=`` or ``GE`` (greater than or equal to), ``==`` or ``IS`` (is), ``¬=``, ``!=``, or ``NE`` (not equal to). If not supplied when ``attribute`` is used, ``EQ`` is assumed.
 
 
 
@@ -208,7 +208,7 @@ resources
     or
       A list of filter expressions to be combined with an ``or`` operation.
 
-      Filter expressions are nested ``complex_filter`` elements.  Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
+      Filter expressions are nested ``complex_filter`` elements. Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
 
 
       | **required**: False
@@ -231,17 +231,17 @@ resources
   filter
     A dictionary with attribute names as keys, and target values, to be used as criteria to filter the set of resources returned from CICSPlex SM.
 
-    Filters implicitly use the ``=`` operator
+    Filters implicitly use the ``=`` operator.
 
-    Filters for ``string`` type attributes can use the ``*`` and ``+`` wildcard operators
+    Filters for ``string`` type attributes can use the ``*`` and ``+`` wildcard operators.
 
-    ``*`` is a wildcard representing an unknown number of characters, and must appear at the end of the value
+    ``*`` is a wildcard representing an unknown number of characters, and must appear at the end of the value.
 
     ``+`` is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times.
 
     To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with ``and`` and ``or`` operators, see the ``complex_filter`` parameter.
 
-    For examples, see :ref:`cmci_get <cmci_get_module>`
+    For examples, see "Examples" in :ref:`cmci_get <cmci_get_module>`.
 
     For more details, see `How to build a filter expression <https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/system-programming/cpsm/eyup1a0.html>`_.
 

docs/source/modules/cmci_update.rst

@@ -158,9 +158,9 @@ resources
 
     Filters can be nested. At most four nesting layers are allowed.
 
-    When supplying the ``attribute`` option, you must also supply a ``value`` for the filter.  You can also override the default operator of ``=`` with the ``operator`` option.
+    When supplying the ``attribute`` option, you must also supply a ``value`` for the filter. You can also override the default operator of ``=`` with the ``operator`` option.
 
-    For examples, see :ref:`cmci_get <cmci_get_module>`
+    For examples, see "Examples" in :ref:`cmci_get <cmci_get_module>`.
 
 
     | **required**: False
@@ -171,7 +171,7 @@ resources
     and
       A list of filter expressions to be combined with an ``and`` operation.
 
-      Filter expressions are nested ``complex_filter`` elements.  Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
+      Filter expressions are nested ``complex_filter`` elements. Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
 
 
       | **required**: False
@@ -191,7 +191,7 @@ resources
 
 
     operator
-      These operators are accepted: ``<`` or ``LT`` (less than), ``<=`` or ``LE`` (less than or equal to), ``=`` or ``EQ`` (equal to), ``>`` or ``GT`` (greater than), ``>=`` or ``GE`` (greater than or equal to), ``==`` or ``IS`` (is), ``¬=``, ``!=``, or ``NE`` (not equal to).  If not supplied when 'attribute' is used, ``EQ`` will be assumed.
+      These operators are accepted: ``<`` or ``LT`` (less than), ``<=`` or ``LE`` (less than or equal to), ``=`` or ``EQ`` (equal to), ``>`` or ``GT`` (greater than), ``>=`` or ``GE`` (greater than or equal to), ``==`` or ``IS`` (is), ``¬=``, ``!=``, or ``NE`` (not equal to). If not supplied when ``attribute`` is used, ``EQ`` is assumed.
 
 
 
@@ -204,7 +204,7 @@ resources
     or
       A list of filter expressions to be combined with an ``or`` operation.
 
-      Filter expressions are nested ``complex_filter`` elements.  Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
+      Filter expressions are nested ``complex_filter`` elements. Each nested filter expression can be either an ``attribute``, ``and`` or ``or`` complex filter expression.
 
 
       | **required**: False
@@ -227,17 +227,17 @@ resources
   filter
     A dictionary with attribute names as keys, and target values, to be used as criteria to filter the set of resources returned from CICSPlex SM.
 
-    Filters implicitly use the ``=`` operator
+    Filters implicitly use the ``=`` operator.
 
-    Filters for ``string`` type attributes can use the ``*`` and ``+`` wildcard operators
+    Filters for ``string`` type attributes can use the ``*`` and ``+`` wildcard operators.
 
-    ``*`` is a wildcard representing an unknown number of characters, and must appear at the end of the value
+    ``*`` is a wildcard representing an unknown number of characters, and must appear at the end of the value.
 
     ``+`` is a wildcard representing a single character, and can appear in any place in the value, potentially multiple times.
 
     To use more complicated filter expressions, including a range of different filter operators, and the ability to compose filters with ``and`` and ``or`` operators, see the ``complex_filter`` parameter.
 
-    For examples, see :ref:`cmci_get <cmci_get_module>`
+    For examples, see "Examples" in :ref:`cmci_get <cmci_get_module>`.
 
     For more details, see `How to build a filter expression <https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/system-programming/cpsm/eyup1a0.html>`_.
 

docs/source/release_notes.rst

@@ -37,13 +37,13 @@ This collection can manage CICS and CICSPlex® SM resources and definitions by c
   * Sample playbooks are available at the `samples repository`_. Each playbook contains a README that explains what configurations must be made to run a sample playbook.
 
 .. _samples repository:
-   https://github.com/IBM/z_ansible_collections_samples/blob/master/README.md
+   https://github.com/IBM/z_ansible_collections_samples/tree/master/cics/cmci
 
 .. _CMCI REST API:
    https://www.ibm.com/support/knowledgecenter/SSGMCP_5.6.0/fundamentals/cpsm/cpsm-cmci-restfulapi-overview.html
 
 .. _the documentation site:
-   https://ansible-collections.github.io/ibm_zos_cics/
+   https://ibm.github.io/z_ansible_collections_doc/ibm_zos_cics/docs/ansible_content.html
 
 Availability
 ------------

docs/source/requirements_managed.rst

@@ -23,22 +23,29 @@ The requirements of the managed node are as follows:
   * `xmltodict`_
 
   If you delegate the tasks to run on your localhost, the Python module dependencies
-  need to be installed on your localhost instead. You can install them from CLI:
+  need to be installed on your localhost instead.
+
+  You can install them from CLI:
 
   .. code-block:: sh
 
      pip install requests xmltodict
 
-  You can also install them using the playbook. See this sample (link to be added) for an example.
+  You can also install them using the playbook. For example, this `CICS
+  sample playbook`_ shows how you can ensure the pre-requisites are installed before the module is executed.
 
 .. _requests:
    https://pypi.org/project/requests/
 
 .. _xmltodict:
    https://pypi.org/project/xmltodict/
 
+.. _CICS sample playbook:
+   https://github.com/IBM/z_ansible_collections_samples/tree/master/cics/cmci/reporting
+
 
-If you use the CICS collection in conjunction with other IBM z/OS collections, you won't be able to delegate all tasks to your localhost. In that case, your managed node must also follow the requirements of those collections, for example, `IBM z/OS core managed node requirements`_.
+If you use the CICS collection in conjunction with other IBM z/OS collections,
+your managed node must also follow the requirements of those collections, for example, `IBM z/OS core managed node requirements`_.
 
 If you use the CICS collection alone but don't delegate the CICS tasks to your localhost, your managed node must also follow the `IBM z/OS core managed node requirements`_ except that IBM Z Open Automation Utilities (ZOAU) is not required.