Reworked and renamed script to generate Ansible collections

The script utils/build-galaxy-release.sh has been renamed to
utils/build-collection.sh, the script provides the same options, but
requires an extra argument now:

    build-collection.sh [options] rpm|aah|galaxy

The namespace and name are defined according to the argument:

    rpm     freeipa.ansible_freeipa   - General use and RPMs
    galaxy  freeipa.ansible_freeipa   - Ansible Galaxy
    aah     redhat.rhel_idm           - Ansible AutomationHub

The generated file README-COLLECTION.md is set in galaxy.yml as the
documentation entry point for the collections generated with aah and galaxy
as Ansible AutomationHub and also Ansible Galaxy are not able to render the
documentation README files in the collection properly.

The commit also changes the calls of utils/build-galaxy-release.sh to
utils/build-collection.sh.

.github/workflows/lint.yml

@@ -17,8 +17,8 @@ jobs:
       - name: Run ansible-lint
         run: |
           pip install "ansible-core>=2.16,<2.17" 'ansible-lint==6.22'
-          utils/build-galaxy-release.sh -ki
+          utils/build-collection.sh -ki rpm
-          cd .galaxy-build
+          cd .collection-build
           ansible-lint --profile production --exclude tests/integration/ --exclude tests/unit/ --parseable --nocolor
 
   yamllint:

infra/azure/templates/run_tests.yml

@@ -54,7 +54,7 @@ jobs:
 
   - script: |
       git fetch --unshallow
-      utils/build-galaxy-release.sh -i
+      utils/build-collection.sh -i rpm
     retryCountOnTaskFailure: 5
     displayName: Build Galaxy release
     condition: ${{ parameters.test_galaxy }}

tests/sanity/sanity.sh

@@ -19,7 +19,7 @@ pip install galaxy_importer
 rm -f "$ANSIBLE_COLLECTION"-*.tar.gz
 rm -f importer_result.json
 
-utils/build-galaxy-release.sh
+utils/build-collection.sh rpm
 
 sed "s/LOCAL_IMAGE_DOCKER = True/LOCAL_IMAGE_DOCKER = ${use_docker}/" < tests/sanity/galaxy-importer.cfg > ${VENV}/galaxy-importer.cfg
 export GALAXY_IMPORTER_CONFIG=${VENV}/galaxy-importer.cfg

utils/build-collection.sh

@@ -8,21 +8,28 @@ pwd=$(pwd)
 
 usage() {
     cat <<EOF
-Usage: $prog [options] [<namespace> <name>]
+Usage: $prog [options] rpm|aah|galaxy
 
 Build Anible Collection for ansible-freeipa.
 
-The namespace defaults to freeipa an name defaults to ansible_freeipa,
+The namespace and name are defined according to the argument:
-if namespace and name are not given. Namespace and name need to be set
+
-together.
+  rpm     freeipa.ansible_freeipa   - General use and RPMs
+  galaxy  freeipa.ansible_freeipa   - Ansible Galaxy
+  aah     redhat.rhel_idm           - Ansible AutomationHub
+
+The generated file README-COLLECTION.md is set in galaxy.yml as the
+documentation entry point for the collections generated with aah and galaxy
+as Ansible AutomationHub and also Ansible Galaxy are not able to render the
+documentation README files in the collection properly.
 
 Options:
-  -a          Add all files, no only files known to git repo
+  -a          Add all files, not only files known to git repo
   -k          Keep build directory
   -i          Install the generated collection
   -o <A.B.C>  Build offline without using git, using version A.B.C
               Also enables -a
-  -p <path>   Installation the generated collection in the path, the
+  -p <path>   Install the generated collection in the given path, the
               ansible_collections sub directory will be created and will
               contain the collection: ansible_collections/<namespace>/<name>
               Also enables -i
@@ -36,7 +43,9 @@ keep=0
 install=0
 path=
 offline=
-galaxy_version=
+version=
+namespace="freeipa"
+name="ansible_freeipa"
 while getopts "ahkio:p:" arg; do
     case $arg in
         a)
@@ -53,7 +62,7 @@ while getopts "ahkio:p:" arg; do
             install=1
             ;;
         o)
-            galaxy_version=$OPTARG
+            version=$OPTARG
             offline=1
             all=1
             ;;
@@ -70,60 +79,97 @@ while getopts "ahkio:p:" arg; do
 done
 shift $((OPTIND-1))
 
-if [ $# != 0 ] && [ $# != 2 ]; then
+if [ $# != 1 ]; then
     usage
     exit 1
 fi
-namespace="${1-freeipa}"
+
-name="${2-ansible_freeipa}"
+collection="$1"
-if [ -z "$namespace" ]; then
+case "$collection" in
-    echo "Namespace might not be empty"
+    rpm|galaxy)
-    exit 1
+        # namespace and name are already set
-fi
+        ;;
-if [ -z "$name" ]; then
+    aah)
-    echo "Name might not be empty"
+        namespace="redhat"
-    exit 1
+        name="rhel_idm"
-fi
+        ;;
+    *)
+        echo "Unknown collection '$collection'"
+        usage
+        exit 1
+        ;;
+esac
 collection_prefix="${namespace}.${name}"
+collection_uname="${collection^^}"
 
-[ -z "$galaxy_version" ] && \
+[ -z "$version" ] && \
-    galaxy_version=$(git describe --tags 2>/dev/null | sed -e "s/^v//")
+    version=$(git describe --tags 2>/dev/null | sed -e "s/^v//")
 
-if [ -z "$galaxy_version" ]; then
+if [ -z "$version" ]; then
     echo "Version could not be detected"
     exit 1
 fi
 
-echo "Building collection: ${namespace}-${name}-${galaxy_version}"
+echo "Building collection: ${namespace}-${name}-${version} for ${collection_uname}"
 
-GALAXY_BUILD=".galaxy-build"
+BUILD=".collection-build"
 
-if [ -e "$GALAXY_BUILD" ]; then
+if [ -e "$BUILD" ]; then
-    echo "Removing existing $GALAXY_BUILD ..."
+    echo "Removing existing $BUILD ..."
-    rm -rf "$GALAXY_BUILD"
+    rm -rf "$BUILD"
-    echo -e "\033[ARemoving existing $GALAXY_BUILD ... \033[32;1mDONE\033[0m"
+    echo -e "\033[ARemoving existing $BUILD ... \033[32;1mDONE\033[0m"
 fi
-mkdir "$GALAXY_BUILD"
+mkdir "$BUILD"
-echo "Copying files to build dir $GALAXY_BUILD ..."
+echo "Copying files to build dir $BUILD ..."
 if [ $all == 1 ]; then
-    # Copy all files except galaxy build dir
+    # Copy all files except collection build dir
     for file in .[A-z]* [A-z]*; do
-        [[ "$file" == "${GALAXY_BUILD}" ]] && continue
+        [[ "$file" == "${BUILD}" ]] && continue
-        cp -a "$file" "${GALAXY_BUILD}/"
+        cp -a "$file" "${BUILD}/"
     done
 else
     # git ls-tree is quoting, therefore ignore SC2046: Quote this to prevent
     # word splitting
     # shellcheck disable=SC2046
-    tar -cf - $(git ls-tree HEAD --name-only -r) | (cd "$GALAXY_BUILD/" && tar -xf -)
+    tar -cf - $(git ls-tree HEAD --name-only -r) | (cd "$BUILD/" && tar -xf -)
 fi
-echo -e "\033[ACopying files to build dir $GALAXY_BUILD ... \033[32;1mDONE\033[0m"
+echo -e "\033[ACopying files to build dir $BUILD ... \033[32;1mDONE\033[0m"
-cd "$GALAXY_BUILD" || exit 1
+cd "$BUILD" || exit 1
 
-sed -i -e "s/version: .*/version: \"$galaxy_version\"/" galaxy.yml
+echo "Removing .copr, .git* and .pre* files from build dir $BUILD ..."
+rm -rf .copr .git* .pre*
+echo -e "\033[ARemoving files from build dir $BUILD ... \033[32;1mDONE\033[0m"
+
+if [ "$collection" != "rpm" ]; then
+    cat > README-COLLECTION.md <<EOF
+FreeIPA Ansible collection
+==========================
+
+Important
+---------
+
+For the documentation of this collection, please have a look at the documentation in the collection archive. Starting point: Base collection directory, file \`README.md\`.
+
+${collection_uname} is not providing proper user documentation nor is able to render the documentation part of the collection. Please ignore any modules and plugins in ${collection_uname} documentation section with the prefix \`ipaserver_\`, \`ipareplica_\`, \`ipaclient_\`, \`ipabackup_\` and \`ipasmartcard_\` and also \`module_utils\` and \`doc_fragments\`. These files are used internally only and are not supported to be used otherwise.
+
+There is the [generic ansible-freeipa upstream documentation](https://github.com/freeipa/ansible-freeipa/blob/v${version}/README.md) specific to the version and also the [latest generic ansible-freeipa upstream documentation](https://github.com/freeipa/ansible-freeipa/blob/master/README.md), both without using the collection prefix \`${collection_prefix}\`.
+EOF
+    if [ "$collection" == "aah" ]; then
+        cat >> README-COLLECTION.md <<EOF
+
+Support
+-------
+
+This collection is maintained by Red Hat RHEL team.
+
+As Red Hat Ansible Certified Content, this collection is entitled to support through the Ansible Automation Platform (AAP) using the **Create issue** button on the top right corner.
+EOF
+    fi
+    sed -i -e "s/readme: .*/readme: README-COLLECTION.md/" galaxy.yml
+fi
+sed -i -e "s/version: .*/version: \"$version\"/" galaxy.yml
 sed -i -e "s/namespace: .*/namespace: \"$namespace\"/" galaxy.yml
 sed -i -e "s/name: .*/name: \"$name\"/" galaxy.yml
-
 find . -name "*~" -exec rm {} \;
 find . -name "__py*__" -exec rm -rf {} \;
 
@@ -210,14 +256,14 @@ ansible-galaxy collection build --force --output-path="$pwd"
 cd "$pwd" || exit 1
 
 if [ $keep == 0 ]; then
-    echo "Removing build dir $GALAXY_BUILD ..."
+    echo "Removing build dir $BUILD ..."
-    rm -rf "$GALAXY_BUILD"
+    rm -rf "$BUILD"
-    echo -e "\033[ARemoving build dir $GALAXY_BUILD ... \033[32;1mDONE\033[0m"
+    echo -e "\033[ARemoving build dir $BUILD ... \033[32;1mDONE\033[0m"
 else
-    echo "Keeping build dir $GALAXY_BUILD"
+    echo "Keeping build dir $BUILD"
 fi
 
 if [ $install == 1 ]; then
-    echo "Installing collection ${namespace}-${name}-${galaxy_version}.tar.gz ..."
+    echo "Installing collection ${namespace}-${name}-${version}.tar.gz ..."
-    ansible-galaxy collection install ${path:+"-p$path"} "${namespace}-${name}-${galaxy_version}.tar.gz" --force ${offline/1/--offline}
+    ansible-galaxy collection install ${path:+"-p$path"} "${namespace}-${name}-${version}.tar.gz" --force ${offline/1/--offline}
 fi