Merge pull request #122 from ansible-collections/release-v1.3.0-beta.1

Merge `release-v1.3.0-beta.1` branch back into `dev` after release.

Author: ddgandhi

README.md

@@ -27,7 +27,7 @@ application deployment in one easy-to-use platform.
 community supported.
 
 For **guides** and **reference**, please visit [the documentation
-site](https://ansible-collections.github.io/ibm_zos_ims/).
+site](https://ibm.github.io/z_ansible_collections_doc/index.html).
 
 Features
 ========
@@ -40,7 +40,7 @@ and ansible-doc to automate tasks on IMS.
 Ansible version compatibility
 ==============================
 
-This collection has been tested against the following Ansible versions: >=2.9,<=2.14.1.
+This collection has been tested against the following Ansible versions: >=2.14.0,<2.16.0.
 
 
 Copyright

docs/Makefile

@@ -9,12 +9,11 @@ SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 ROOT_DIR:=$(shell dirname $(realpath $(firstword $(MAKEFILE_LIST))))
+OS_DISTRO := $(shell uname)
+INDEX_HTML = build/html/index.html
 line_header="===================================================================="
 
-
-view-html:
-	@echo "Display generated HTML in default browser."
-	@open build/html/index.html
+.PHONY: help Makefile
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -48,7 +47,19 @@ help:
 	@echo $(line_header)
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+view-html:
+ifeq ($(shell test -e $(INDEX_HTML) && echo true),true)
+	@echo "Display generated HTML '$(INDEX_HTML)' in default browser."
+ifeq ($(OS_DISTRO), Darwin)
+	@open build/html/index.html
+else ifeq ($(OS_DISTRO), Linux)
+	@xdg-open build/html/index.html &> /dev/null &
+else
+	@echo "Unable to launch browser for $(INDEX_HTML), open file with your browser."
+endif
+else
+	@echo "Unable to find generated HTML '$(INDEX_HTML)'."
+endif
 
 clean:
 	@echo $(line_header)
@@ -98,16 +109,16 @@ role-doc:
 	fi
 
 	@for role_name in `ls ../roles/`; do \
-	echo "Detected role name $$role_name"; \
-	if test -e ../roles/$$role_name/docs/doc_$$role_name; then \
-	echo "Copying metadata ../roles/$$role_name/docs/doc_$$role_name to ../roles/$$role_name/docs/doc_$$role_name.py"; \
-	cp ../roles/$$role_name/docs/doc_$$role_name ../roles/$$role_name/docs/doc_$$role_name.py; \
-	echo "Sanitizing metadata ../roles/$$role_name/docs/doc_$$role_name.py"; \
-	sed -i "" "s/role:/module:/g" ../roles/$$role_name/docs/doc_$$role_name.py; \
-	echo "Generating RST doc for role ../roles/$$role_name"; \
-	ansible-doc-extractor --template templates/role.rst.j2 source/roles ../roles/$$role_name/docs/doc_$$role_name.py; \
-	echo "Deleting generated metadata ../roles/$$role_name/docs/doc_$$role_name.py"; \
-	rm -rf ../roles/$$role_name/docs/doc_$$role_name.py; \
+		echo "Detected role name $$role_name"; \
+		if test -e ../roles/$$role_name/docs/doc_$$role_name; then \
+		echo "Copying metadata ../roles/$$role_name/docs/doc_$$role_name to ../roles/$$role_name/docs/doc_$$role_name.py"; \
+		cp ../roles/$$role_name/docs/doc_$$role_name ../roles/$$role_name/docs/doc_$$role_name.py; \
+		echo "Sanitizing metadata ../roles/$$role_name/docs/doc_$$role_name.py"; \
+		sed -i -e "s/^role:/module:/" ../roles/$$role_name/docs/doc_$$role_name.py; \
+		echo "Generating RST doc for role ../roles/$$role_name"; \
+		ansible-doc-extractor --template templates/role.rst.j2 source/roles ../roles/$$role_name/docs/doc_$$role_name.py; \
+		echo "Deleting generated metadata ../roles/$$role_name/docs/doc_$$role_name.py"; \
+		rm -rf ../roles/$$role_name/docs/doc_$$role_name.py; \
 	fi; \
 	done
 
@@ -130,40 +141,49 @@ module-doc:
 	mkdir -p source/modules; \
 	fi
 
-	@if ! test -d ../plugins/modules/rexx_module_doc; then \
-	echo "Make ../plugins/modules/rexx_module_doc directory to extract REXX doc into temporary file."; \
-	mkdir -p ../plugins/modules/rexx_module_doc; \
-	else \
-	echo "Delete ../plugins/modules/rexx_module_doc directory used to extract REXX doc into temporary file."; \
-	rm -rf ../plugins/modules/rexx_module_doc; \
-	echo "Make ../plugins/modules/rexx_module_doc directory to extract REXX doc into temporary file."; \
-	mkdir -p ../plugins/modules/rexx_module_doc; \
-	fi
-
-	@for rexx_module in `ls ../plugins/modules/*rexx`; do\
-	   REXX_FILE=`basename $$rexx_module .rexx`; \
-	   echo "Extracting documentation for module $$REXX_FILE into ../plugins/modules/rexx_module_doc/$$REXX_FILE.py"; \
-	   touch ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
-	   sed -n "/DOCUMENTATION = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
-	   sed -n "/EXAMPLES = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
-	   sed -n "/RETURN = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
-	   echo "Generating ReStructuredText for module $$REXX_FILE inot source/modules/$$REXX_FILE.rst"; \
-	   ansible-doc-extractor --template templates/module.rst.j2 source/modules ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
-	done
-
-	@if test -d ../plugins/modules/rexx_module_doc; then \
-	echo "Delete ../plugins/modules/rexx_module_doc directory used to extract REXX doc into temporary file."; \
-	rm -rf ../plugins/modules/rexx_module_doc; \
-	fi
+	# @if ! test -d ../plugins/modules/rexx_module_doc; then \
+	# echo "Make ../plugins/modules/rexx_module_doc directory to extract REXX doc into temporary file."; \
+	# mkdir -p ../plugins/modules/rexx_module_doc; \
+	# else \
+	# echo "Delete ../plugins/modules/rexx_module_doc directory used to extract REXX doc into temporary file."; \
+	# rm -rf ../plugins/modules/rexx_module_doc; \
+	# echo "Make ../plugins/modules/rexx_module_doc directory to extract REXX doc into temporary file."; \
+	# mkdir -p ../plugins/modules/rexx_module_doc; \
+	# fi
+
+	# @for rexx_module in `ls ../plugins/modules/*rexx`; do\
+	#    REXX_FILE=`basename $$rexx_module .rexx`; \
+	#    echo "Extracting documentation for module $$REXX_FILE into ../plugins/modules/rexx_module_doc/$$REXX_FILE.py"; \
+	#    touch ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
+	#    sed -n "/DOCUMENTATION = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
+	#    sed -n "/EXAMPLES = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
+	#    sed -n "/RETURN = '''/,/'''/p" ../plugins/modules/$$REXX_FILE.rexx >> ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
+	#    echo "Generating ReStructuredText for module $$REXX_FILE inot source/modules/$$REXX_FILE.rst"; \
+	#    ansible-doc-extractor --template templates/module.rst.j2 source/modules ../plugins/modules/rexx_module_doc/$$REXX_FILE.py; \
+	# done
+
+	# @if test -d ../plugins/modules/rexx_module_doc; then \
+	# echo "Delete ../plugins/modules/rexx_module_doc directory used to extract REXX doc into temporary file."; \
+	# rm -rf ../plugins/modules/rexx_module_doc; \
+	# fi
 
 	@if test -e ../plugins/modules/__init__.py; then \
 	echo "Rename file '../plugins/modules/__init__.py' to ../plugins/modules/__init__.py.skip to avoid reading empty python file.'"; \
 	mv ../plugins/modules/__init__.py ../plugins/modules/__init__.py.skip; \
 	fi
 
+	@echo "Replacing string based carriage returns with literal escaped to produce sphynx consumable RST."
+	scripts/pre-template.sh
+
 	@echo "Generating ReStructuredText for all ansible modules found at '../plugins/modules/' to 'source/modules'."
 	@ansible-doc-extractor --template templates/module.rst.j2 source/modules ../plugins/modules/*.py
 
+	@echo "Updating zos_apf file."
+	scripts/post-zos_apf.sh
+
+	@echo "Reverting edited source file."
+	scripts/post-template.sh
+
 	@if test -e ../plugins/modules/__init__.py.skip; \
     echo "Rename file '../plugins/modules/__init__.py.skip' back to ../plugins/modules/__init__.py.'"; \
 	then mv -f ../plugins/modules/__init__.py.skip ../plugins/modules/__init__.py; \

docs/ansible_content.rst

@@ -14,7 +14,8 @@ Ansible® Automation to IBM Z through the offering
 The **IBM z/OS IMS collection** supports tasks such as generating
 IMS Database Descriptors (DBD), Program Specification Blocks (PSB),
 Application Control Blocks (ACB), running IMS commands
-(type-1, type-2, DBRC), and interacting with the IMS Catalog.
+(type-1, type-2, DBRC), interacting with the IMS Catalog, and
+the IMS Data Definition Language Utility (DDL).
 
 The Ansible modules in this collection are written in Python and
 interact with the `IBM z/OS core collection`_ and

docs/scripts/auto-doc-gen.sh

@@ -2,6 +2,15 @@
 
 ################################################################################
 # © Copyright IBM Corporation 2020
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 ################################################################################
 
 ################################################################################
@@ -16,40 +25,43 @@ DOC_DIR=`( cd "$SCRIPT_PATH" && pwd )| sed 's|\(.*\)/.*|\1|'`
 # Source the playbook*.rst into a single RST so that our topic is a single html
 ################################################################################
 
-# If playbooks-single.rst exists, zero it out so we generate the lastest based
-# on the payboook-*.rst files
-if [[ -f $DOC_DIR/source/playbooks-single.rst  ]]; then
-    :> $DOC_DIR/source/playbooks-single.rst
-fi
-
-# Remove the first toctree entry and onwards from playbooks.rst to create a new
-# RST playbooks-single.rst. Note, you should ensure toctree entries are at the
-# end of the conent to not remove unwanted content.
-if [[ -f $DOC_DIR/source/playbooks.rst ]]; then
-
-    # Remove the toctree entries
-    awk '/toctree/ {exit} {print}' $DOC_DIR/source/playbooks.rst >> $DOC_DIR/source/playbooks-single.rst
-
-    # Concat the interested RSTs into playbooks-single.rst to create a single RST
-    if [[ -f $DOC_DIR/source/playbook_config_setup.rst && -f $DOC_DIR/source/playbook_inventory.rst && -f $DOC_DIR/source/playbook_group_vars.rst && -f $DOC_DIR/source/playbook_run.rst ]]; then
-
-        # Inform readers this is auto generated thus avoding the need to maintain
-        echo ".. ...........................................................................\n$(<$DOC_DIR/source/playbooks-single.rst)" > $DOC_DIR/source/playbooks-single.rst
-        echo ".. Auto generated restructured text                                          .\n$(<$DOC_DIR/source/playbooks-single.rst)" > $DOC_DIR/source/playbooks-single.rst
-        echo ".. ...........................................................................\n$(<$DOC_DIR/source/playbooks-single.rst)" > $DOC_DIR/source/playbooks-single.rst
-
-        # For each identified file we want to merge into playbooks-single.rst cat them and merge
-        for file in $DOC_DIR/source/playbook_config_setup.rst $DOC_DIR/source/playbook_inventory.rst $DOC_DIR/source/playbook_group_vars.rst $DOC_DIR/source/playbook_run.rst; do
-            echo "" >> $DOC_DIR/source/playbooks-single.rst;
-            cat "$file" >> $DOC_DIR/source/playbooks-single.rst;
-        done
-    else
-        # When unable to merge remove the auto generated RST so that is apparent
-        # it is not generated and will diff in a 'git status'
-
-        rm -rf $DOC_DIR/source/playbooks-single.rst
-    fi
-fi
+################################################################################
+# Deprecated playbooks-single.rst
+# # If playbooks-single.rst exists, zero it out so we generate the lastest based
+# # on the payboook-*.rst files
+# if [[ -f $DOC_DIR/source/playbooks-single.rst  ]]; then
+#     :> $DOC_DIR/source/playbooks-single.rst
+# fi
+
+# # Remove the first toctree entry and onwards from playbooks.rst to create a new
+# # RST playbooks-single.rst. Note, you should ensure toctree entries are at the
+# # end of the conent to not remove unwanted content.
+# if [[ -f $DOC_DIR/source/playbooks.rst ]]; then
+
+#     # Remove the toctree entries
+#     awk '/toctree/ {exit} {print}' $DOC_DIR/source/playbooks.rst >> $DOC_DIR/source/playbooks-single.rst
+
+#     # Concat the interested RSTs into playbooks-single.rst to create a single RST
+#     if [[ -f $DOC_DIR/source/playbook_config_setup.rst && -f $DOC_DIR/source/playbook_inventory.rst && -f $DOC_DIR/source/playbook_group_vars.rst && -f $DOC_DIR/source/playbook_run.rst ]]; then
+
+#         # Inform readers this is auto generated thus avoding the need to maintain
+#         echo ".. ...........................................................................\n$(<$DOC_DIR/source/playbooks-single.rst)" > $DOC_DIR/source/playbooks-single.rst
+#         echo ".. Auto generated restructured text                                          .\n$(<$DOC_DIR/source/playbooks-single.rst)" > $DOC_DIR/source/playbooks-single.rst
+#         echo ".. ...........................................................................\n$(<$DOC_DIR/source/playbooks-single.rst)" > $DOC_DIR/source/playbooks-single.rst
+
+#         # For each identified file we want to merge into playbooks-single.rst cat them and merge
+#         for file in $DOC_DIR/source/playbook_config_setup.rst $DOC_DIR/source/playbook_inventory.rst $DOC_DIR/source/playbook_group_vars.rst $DOC_DIR/source/playbook_run.rst; do
+#             echo "" >> $DOC_DIR/source/playbooks-single.rst;
+#             cat "$file" >> $DOC_DIR/source/playbooks-single.rst;
+#         done
+#     else
+#         # When unable to merge remove the auto generated RST so that is apparent
+#         # it is not generated and will diff in a 'git status'
+
+#         rm -rf $DOC_DIR/source/playbooks-single.rst
+#     fi
+# fi
+################################################################################
 
 # If requirements-single.rst exists, zero it out so we generate the lastest based
 # on the requirements-*.rst files

docs/scripts/post-doc-gen.sh

@@ -2,6 +2,15 @@
 
 ################################################################################
 # © Copyright IBM Corporation 2020
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 ################################################################################
 
 ################################################################################

docs/scripts/post-template.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+
+################################################################################
+# © Copyright IBM Corporation 2020
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+################################################################################
+# This scripts actions called before after generating RST such that the
+# original template.py is put back in its original state.
+################################################################################
+
+# Obtain the galaxy collection installion up to the template.py located on the host
+template_doc_source=`ansible-config dump|grep DEFAULT_MODULE_PATH| cut -d'=' -f2|sed 's/[][]//g' | tr -d \'\" |sed 's/modules/doc_fragments\/template.py/g'`
+mv $template_doc_source.tmp $template_doc_source

docs/scripts/pre-doc-gen.sh

@@ -1,7 +1,16 @@
 #!/bin/sh
 
 ################################################################################
-# © Copyright IBM Corporation 2020
+# © Copyright IBM Corporation 2023
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 ################################################################################
 
 ################################################################################

docs/scripts/pre-template.sh

@@ -0,0 +1,32 @@
+#!/bin/sh
+
+################################################################################
+# © Copyright IBM Corporation 2023
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+################################################################################
+# This scripts actions called before generating RST, this scripts leaves the
+# "\n", "\r", "\r\n" in the template.py doc_fragment so that ansible linting
+# test will pass such that the doc and module are match. Later this script will
+# update the above strings to liters with an esacpe, for example "\n" --> '\\n'.
+# This allows for RST to be generated that is usable by the ansible-doc-extractor
+# and Jinja2 template, and later sphinx html.
+# This requries that the ansible collection be prebuilt so that it can find
+# the template.py within the collection (not within the git project). Thus run
+# './ac --ac-build' before the make file that builds doc. 
+################################################################################
+
+template_doc_source=`ansible-config dump|grep DEFAULT_MODULE_PATH| cut -d'=' -f2|sed 's/[][]//g' | tr -d \'\" |sed 's/modules/doc_fragments\/template.py/g'`
+cp $template_doc_source $template_doc_source.tmp
+sed -i '' "s/\"\\\\n\"/'\\\\\\\\n'/g" $template_doc_source
+sed -i '' "s/\"\\\\r\"/'\\\\\\\\r'/g" $template_doc_source
+sed -i '' "s/\"\\\\r\\\\n\"/'\\\\\\\\r\\\\\\\\n'/g" $template_doc_source