[PR #11922/cdd0d252 backport][stable-12] jenkins_credential: improve example and description in documentation (#12016)

jenkins_credential: improve example and description in documentation (#11922)

* Fixes and improvements for better undestanding of the module

- Fixed token generation syntax to use `name` instead of `id`.
- Changed `token: {{ token }}` to `token: {{ token_result.token }}` to show accessing token from the registered variable, essentially making the entire Example section a playbook capable of full execution.
- Added notes in the Example section about the intended approach for storing and accessing tokens.
- Mentioned about not using `id` for token generation in the parameter's description.

* Applying FQCN for the `ansible.builtin.copy` module



* Shortened the notes about storing and accessing Jenkins token.

* Added line breaks to reduce width of the shortened notes

- Added line breaks to reduce the width of the shortened note from commit #5bc225b.
- Numbered and indented the notes for clear distinction.

* Changed token storage example to use INI instead of CSV format

---------


(cherry picked from commit cdd0d2521e)

Co-authored-by: Sonal Karmakar <234934724+sonalkarmakar@users.noreply.github.com>
Co-authored-by: Felix Fontein <felix@fontein.de>

plugins/modules/jenkins_credential.py

@@ -30,6 +30,7 @@ options:
   id:
     description:
       - The ID of the Jenkins credential or domain.
+      - When generating a new token, do not pass O(id). It is generated automatically.
     type: str
   type:
     description:
@@ -187,18 +188,37 @@ options:
 EXAMPLES = r"""
 - name: Generate token
   community.general.jenkins_credential:
-    id: "test-token"
+    name: "test-token"
     jenkins_user: "admin"
     jenkins_password: "password"
     type: "token"
   register: token_result
 
+- name: Save Jenkins token to INI file (you must secure/encrypt separately)
+  vars:
+    jenkins_token_ini: # Defining dict for to_ini filter
+      api_token:
+        uuid: "{{ token_result.token_uuid }}"
+        token: "{{ token_result.token }}"
+  ansible.builtin.copy:
+    dest: "/secure/path/jenkins_token.ini"
+    mode: '0600'
+    content: "{{ jenkins_token_ini | community.general.to_ini }}"
+
+# Note:
+# (1) Jenkins token is intended to be securely stored in encrypted storage
+#     or secrets vault outside the playbook, retrieved when needed.
+# (2) Examples below showcasing token retrieval from
+#     variable "token_result" are NOT how it should be used to add credentials.
+# (3) Data in "token_result" is inconsistent and unavailable
+#     across different playbooks and multiple executions.
+
 - name: Add CUSTOM scope credential
   community.general.jenkins_credential:
     id: "CUSTOM"
     type: "scope"
     jenkins_user: "admin"
-    token: "{{ token }}"
+    token: "{{ token_result.token }}"
     description: "Custom scope credential"
     inc_path:
       - "include/path"
@@ -227,7 +247,7 @@ EXAMPLES = r"""
     id: "userpass-id"
     type: "user_and_pass"
     jenkins_user: "admin"
-    token: "{{ token }}"
+    token: "{{ token_result.token }}"
     description: "User and password credential"
     username: "user1"
     password: "pass1"
@@ -237,7 +257,7 @@ EXAMPLES = r"""
     id: "file-id"
     type: "file"
     jenkins_user: "admin"
-    token: "{{ token }}"
+    token: "{{ token_result.token }}"
     scope: "CUSTOM"
     description: "File credential"
     file_path: "../vars/my-secret.pem"
@@ -247,7 +267,7 @@ EXAMPLES = r"""
     id: "text-id"
     type: "text"
     jenkins_user: "admin"
-    token: "{{ token }}"
+    token: "{{ token_result.token }}"
     description: "Text credential"
     secret: "mysecrettext"
     location: "folder"
@@ -258,7 +278,7 @@ EXAMPLES = r"""
     id: "githubapp-id"
     type: "github_app"
     jenkins_user: "admin"
-    token: "{{ token }}"
+    token: "{{ token_result.token }}"
     description: "GitHub app credential"
     appID: "12345"
     file_path: "../vars/github.pem"
@@ -269,7 +289,7 @@ EXAMPLES = r"""
     id: "sshkey-id"
     type: "ssh_key"
     jenkins_user: "admin"
-    token: "{{ token }}"
+    token: "{{ token_result.token }}"
     description: "SSH key credential"
     username: "sshuser"
     file_path: "../vars/ssh_key"
@@ -280,7 +300,7 @@ EXAMPLES = r"""
     id: "certificate-id"
     type: "certificate"
     jenkins_user: "admin"
-    token: "{{ token }}"
+    token: "{{ token_result.token }}"
     description: "Certificate credential"
     password: "12345678901234"
     file_path: "../vars/certificate.p12"
@@ -290,7 +310,7 @@ EXAMPLES = r"""
     id: "certificate-id-pem"
     type: "certificate"
     jenkins_user: "admin"
-    token: "{{ token }}"
+    token: "{{ token_result.token }}"
     description: "Certificate credential (pem)"
     file_path: "../vars/cert.pem"
     private_key_path: "../vars/private.key"