Fix make gendocs error; temporarily pin CI to Python 3.13; parallelize documentation generation (#726)

* Fix make gendocs error; parallelize documentation generation

* Bump docs workflow to 3.13

* oops

* Pin versions

Author: lgarber-akamai

.github/workflows/docs.yml

@@ -3,7 +3,7 @@ name: Run Documentation Validation
 on: pull_request
 
 env:
-  DEFAULT_PYTHON_VERSION: "3.10"
+  DEFAULT_PYTHON_VERSION: "3.13"
 
 jobs:
   test-templated-docs:

.github/workflows/integration-tests-pr.yml

@@ -42,7 +42,8 @@ jobs:
       - name: setup python 3
         uses: actions/setup-python@v6
         with:
-          python-version: '3.x'
+          # TODO: Unpin minor version after `ansible` package v13.0.0 releases.
+          python-version: '3.13'
 
       - name: install ansible dependencies
         run: ansible-galaxy collection install amazon.aws:==9.5.0
@@ -146,7 +147,8 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.x'
+          # TODO: Unpin minor version after `ansible` package v13.0.0 releases.
+          python-version: '3.13'
 
       - name: Install Linode CLI
         run: |

.github/workflows/integration-tests.yml

@@ -91,7 +91,8 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.x'
+          # TODO: Unpin minor version after `ansible` package v13.0.0 releases.
+          python-version: '3.13'
 
       - name: Install Python dependencies
         run: pip3 install requests wheel boto3==1.35.99
@@ -176,7 +177,8 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.x'
+          # TODO: Unpin minor version after `ansible` package v13.0.0 releases.
+          python-version: '3.13'
 
       - name: Install Linode CLI
         run: |

.github/workflows/lint.yml

@@ -12,7 +12,8 @@ jobs:
       - name: setup python 3
         uses: actions/setup-python@v6
         with:
-          python-version: '3.x'
+          # TODO: Unpin minor version after `ansible` package v13.0.0 releases.
+          python-version: '3.13'
 
       - name: install dependencies
         run: make deps

.github/workflows/release.yml

@@ -21,7 +21,8 @@ jobs:
       - name: setup python 3
         uses: actions/setup-python@v6
         with:
-          python-version: '3.x'
+          # TODO: Unpin minor version after `ansible` package v13.0.0 releases.
+          python-version: '3.13'
 
       - name: install dependencies
         run: make deps

.github/workflows/unit-tests.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ '3.9','3.10','3.11', '3.12' ]
+        python-version: [ '3.10','3.11', '3.12', '3.13' ]
     defaults:
       run:
         working-directory: .ansible/collections/ansible_collections/linode/cloud

Makefile

@@ -56,7 +56,7 @@ gendocs:
 	mkdir -p $(DOCS_PATH)/modules $(DOCS_PATH)/inventory
 
 	DOCS_PATH=$(DOCS_PATH) ./scripts/specdoc_generate.sh
-	ansible-doc-extractor --template=template/module.rst.j2 $(DOCS_PATH)/inventory plugins/inventory/*.py
+	ansible-doc-extractor --template=template/module.rst.j2 $(DOCS_PATH)/inventory $(abspath plugins/inventory/*.py)
 	python3 scripts/render_readme.py $(COLLECTION_VERSION)
 
 # if want to add all the test add the tag --tags never at the end
@@ -126,11 +126,14 @@ endif
 	@echo "api_version: $${LINODE_API_VERSION:-$${TEST_API_VERSION:-v4beta}}" >> $(INTEGRATION_CONFIG)
 	@echo "ca_file: $${LINODE_CA:-$${TEST_API_CA}}" >> $(INTEGRATION_CONFIG)
 
+
 inject:
 	@echo "Injecting documentation into source files"
-	for f in `ls ./plugins/modules/*.py`; do echo "$$f" && ansible-specdoc -j -i $$f; done
-	ansible-test sanity --test ansible-doc
+	find ./plugins/modules -maxdepth 1 -name '*.py' -print0 | \
+		xargs -I {} -0 -P 5 bash -c 'export TARGET="{}"; echo "$$TARGET" && ansible-specdoc -j -i "$$TARGET";'
 
 inject-clean:
 	@echo "Removing injected documentation from source files"
-	for f in `ls ./plugins/modules/*.py`; do echo "$$f" && ansible-specdoc -jc -i $$f; done
+	find ./plugins/modules -maxdepth 1 -name '*.py' -print0 | \
+		xargs -I {} -0 -P 5 bash -c 'export TARGET="{}"; echo "$$TARGET" && ansible-specdoc -jc -i "$$TARGET";'
+

README.md

@@ -199,6 +199,11 @@ Use-case examples for this collection can be found [here](./examples/README.md).
 
 The following section outlines various information relating to the development of this collection.
 
+### Generating Documentation
+
+This collection's documentation is generated dynamically from the specification defined in each module using 
+[ansible-specdoc](https://github.com/linode/ansible-specdoc).
+
 ### Attaching a Debugger
 
 To quickly and easily attach a debugger to a running module in this collection, 

docs/inventory/instance.rst

@@ -76,29 +76,29 @@ Parameters
 
 
       **parent_group (type=str):**
-        \• parent group for keyed group
+        \• parent group for keyed group.
 
 
       **prefix (type=str):**
-        \• A keyed group name will start with this prefix
+        \• A keyed group name will start with this prefix.
 
 
       **separator (type=str, default=_):**
-        \• separator used to build the keyed group name
+        \• separator used to build the keyed group name.
 
 
       **key (type=str):**
-        \• The key from input dictionary used to generate groups
+        \• The key from input dictionary used to generate groups.
 
 
       **default_value (type=str):**
-        \• The default value when the host variable's value is an empty string.
+        \• The default value when the host variable's value is :literal:`None` or an empty string.
 
         \• This option is mutually exclusive with :literal:`keyed\_groups[].trailing\_separator`.
 
 
       **trailing_separator (type=bool, default=True):**
-        \• Set this option to :literal:`False` to omit the :literal:`keyed\_groups[].separator` after the host variable when the value is an empty string.
+        \• Set this option to :literal:`false` to omit the :literal:`keyed\_groups[].separator` after the host variable when the value is :literal:`None` or an empty string.
 
         \• This option is mutually exclusive with :literal:`keyed\_groups[].default\_value`.
 
@@ -109,13 +109,13 @@ Parameters
 
 
   **leading_separator (type=boolean, default=True):**
-    \• Use in conjunction with keyed\_groups.
+    \• Use in conjunction with :literal:`keyed\_groups`.
 
     \• By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
 
-    \• This is because the default prefix is "" and the default separator is "\_".
+    \• This is because the default prefix is :literal:`""` and the default separator is :literal:`"\_"`.
 
-    \• Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
+    \• Set this option to :literal:`false` to omit the leading underscore (or other separator) if no prefix is given.
 
     \• If the group name is derived from a mapping the separator is still used to concatenate the items.
 

scripts/specdoc_generate.sh

@@ -1,10 +1,17 @@
 #!/bin/bash
 
-DPATH="${DOCS_PATH:="docs"}"
-
-for f in plugins/modules/*.py
-do
-  echo "$f"
-  MODULE_NAME="$(basename "$f" .py)"
-  PYTHONWARNINGS="ignore" ansible-specdoc -i "$f" -f jinja2 -t template/module.md.j2 -o $DPATH/modules/"$MODULE_NAME".md; #> /dev/null || exit 1;
-done
+DOCS_PATH="${DOCS_PATH:="docs"}"
+
+export PYTHONWARNINGS="ignore"
+
+render_module_doc() {
+  MODULE_NAME="$(basename "$1" .py)"
+
+  echo "Rendering: $MODULE_NAME"
+
+  ansible-specdoc -i "$1" -f jinja2 -t template/module.md.j2 -o "$DOCS_PATH/modules/$MODULE_NAME.md"
+}
+
+export -f render_module_doc
+
+find plugins/modules -maxdepth 1 -name '*.py' -print0 | xargs -I {} -0 -P 5 bash -c 'render_module_doc {}'