sar_facts - improves module return docs

[NomakCooper]

SUMMARY

This PR improves the return module documentation

RETURN = r'''
ansible_facts:
  description:
    - A dictionary containing the SAR data collected.
    - The value is a list of dictionaries where each dictionary represents a single data point.
    - V(date) The date for the measurement.
    - V(time) The time for the measurement in 24-hour format.
    - Additional keys corresponding to the performance metrics output from the C(sar) command.
  returned: always
  type: complex
  contains:
    sar_cpu:
      description:
        - Dictionary that contains C(cpu) data from C(sar).
        - It contains V(date), V(time) and all others keys from C(sar) data.
        - Most common keys are V(%user), V(%nice), V(%system), V(%idle) and others.
      returned: when O(type) is V(cpu).
      type: dict
    sar_mem:
      description:
        - Dictionary that contains C(memory) data from C(sar).
        - It contains V(date), V(time) and all others keys from C(sar) data.
        - Most common keys are V(%memused), V(%commit) and others.
      returned: when O(type) is V(memory).
      type: dict
    sar_swap:
      description:
        - Dictionary that contains C(swap) data from C(sar).
        - It contains V(date), V(time) and all others keys from C(sar) data.
        - Most common keys are V(%swpused), V(%swpcad) and others.
      returned: when O(type) is V(swap).
      type: dict
    sar_net:
      description:
        - Dictionary that contains C(network) data from C(sar).
        - It contains V(date), V(time) and all others keys from C(sar) data.
        - Most common keys are V(IFACE), V(rxpck/s), V(txpck/s), v(%ifutil) and others.
      returned: when O(type) is V(network).
      type: dict
    sar_disk:
      description:
        - Dictionary that contains C(disk) data from C(sar).
        - It contains V(date), V(time) and all others keys from C(sar) data.
        - Most common keys are V(DEV), V(%util), V(await), V(rkB/s), V(wkB/s) and others.
      returned: when O(type) is V(disk).
      type: dict
    sar_load:
      description:
        - Dictionary that contains C(load) data from C(sar).
        - It contains V(date), V(time) and all others keys from C(sar) data.
        - Most common keys are V(ldavg-1), V(ldavg-5), V(ldavg-15) and others.
      returned: when O(type) is V(load).
      type: dict
'''

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

sar_facts

ADDITIONAL INFORMATION

[github-actions]

Docs Build 📝

Thank you for contribution!✨

The docs for this PR have been published here:
https://3A2DEV.github.io/ans2dev.general/pr/124

You can compare to the docs for the main branch here:
https://3A2DEV.github.io/ans2dev.general/branch/main

The docsite for this PR is also available for download as an artifact from this run:
https://github.com/3A2DEV/ans2dev.general/actions/runs/14318948613

File changes:

• M sar_facts_module.html

Click to see the diff comparison.

NOTE: only file modifications are shown here. New and deleted files are excluded.
See the file list and check the published docs to see those files.

diff --git a/home/runner/work/ans2dev.general/ans2dev.general/docsbuild/base/sar_facts_module.html b/home/runner/work/ans2dev.general/ans2dev.general/docsbuild/head/sar_facts_module.html
index c98be94..2b63751 100644
--- a/home/runner/work/ans2dev.general/ans2dev.general/docsbuild/base/sar_facts_module.html
+++ b/home/runner/work/ans2dev.general/ans2dev.general/docsbuild/head/sar_facts_module.html
@@ -91,7 +91,8 @@
 <li class="toctree-l1 current"><a class="current reference internal" href="#">ans2dev.general.sar_facts module – Collect system activity report (SAR) data for system performance monitoring.</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="#synopsis">Synopsis</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#parameters">Parameters</a></li>
-<li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#returned-facts">Returned Facts</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#authors">Authors</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#collection-links">Collection links</a></li>
 </ul>
@@ -144,6 +145,7 @@ To check whether it is installed, run <code class="code docutils literal notrans
 <li><p><a class="reference internal" href="#synopsis" id="id1">Synopsis</a></p></li>
 <li><p><a class="reference internal" href="#parameters" id="id2">Parameters</a></p></li>
 <li><p><a class="reference internal" href="#examples" id="id3">Examples</a></p></li>
+<li><p><a class="reference internal" href="#returned-facts" id="id4">Returned Facts</a></p></li>
 </ul>
 </nav>
 <section id="synopsis">
@@ -266,6 +268,79 @@ To check whether it is installed, run <code class="code docutils literal notrans
 <span class="w">    </span><span class="nt">average</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">true</span>
 </pre></div>
 </div>
+</section>
+<section id="returned-facts">
+<h2><a class="toc-backref" href="#id4" role="doc-backlink">Returned Facts</a><a class="headerlink" href="#returned-facts" title="Link to this heading"></a></h2>
+<p>Facts returned by this module are added/updated in the <code class="docutils literal notranslate"><span class="pre">hostvars</span></code> host facts and can be referenced by name just like any other host fact. They do not need to be registered in order to use them.</p>
+<table class="longtable ansible-option-table docutils align-default" style="width: 100%">
+<thead>
+<tr class="row-odd"><th class="head"><p>Key</p></th>
+<th class="head"><p>Description</p></th>
+</tr>
+</thead>
+<tbody>
+<tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="return-ansible_facts/sar_cpu"></div><p class="ansible-option-title" id="ansible-collections-ans2dev-general-sar-facts-module-return-ansible-facts-sar-cpu"><strong>sar_cpu</strong></p>
+<a class="ansibleOptionLink" href="#return-ansible_facts/sar_cpu" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">dictionary</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Dictionary that contains <code class="docutils literal notranslate"><span class="pre">cpu</span></code> data from <code class="docutils literal notranslate"><span class="pre">sar</span></code>.</p>
+<p>It contains <code class="ansible-value docutils literal notranslate"><span class="pre">date</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">time</span></code> and all others keys from <code class="docutils literal notranslate"><span class="pre">sar</span></code> data.</p>
+<p>Most common keys are <code class="ansible-value docutils literal notranslate"><span class="pre">%user</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">%nice</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">%system</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">%idle</span></code> and others.</p>
+<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> when <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-ans2dev-general-sar-facts-module-parameter-type"><span class="std std-ref"><span class="pre">type</span></span></a></strong></code> is <code class="ansible-value docutils literal notranslate"><span class="pre">cpu</span></code>.</p>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="return-ansible_facts/sar_disk"></div><p class="ansible-option-title" id="ansible-collections-ans2dev-general-sar-facts-module-return-ansible-facts-sar-disk"><strong>sar_disk</strong></p>
+<a class="ansibleOptionLink" href="#return-ansible_facts/sar_disk" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">dictionary</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Dictionary that contains <code class="docutils literal notranslate"><span class="pre">disk</span></code> data from <code class="docutils literal notranslate"><span class="pre">sar</span></code>.</p>
+<p>It contains <code class="ansible-value docutils literal notranslate"><span class="pre">date</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">time</span></code> and all others keys from <code class="docutils literal notranslate"><span class="pre">sar</span></code> data.</p>
+<p>Most common keys are <code class="ansible-value docutils literal notranslate"><span class="pre">DEV</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">%util</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">await</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">rkB/s</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">wkB/s</span></code> and others.</p>
+<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> when <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-ans2dev-general-sar-facts-module-parameter-type"><span class="std std-ref"><span class="pre">type</span></span></a></strong></code> is <code class="ansible-value docutils literal notranslate"><span class="pre">disk</span></code>.</p>
+</div></td>
+</tr>
+<tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="return-ansible_facts/sar_load"></div><p class="ansible-option-title" id="ansible-collections-ans2dev-general-sar-facts-module-return-ansible-facts-sar-load"><strong>sar_load</strong></p>
+<a class="ansibleOptionLink" href="#return-ansible_facts/sar_load" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">dictionary</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Dictionary that contains <code class="docutils literal notranslate"><span class="pre">load</span></code> data from <code class="docutils literal notranslate"><span class="pre">sar</span></code>.</p>
+<p>It contains <code class="ansible-value docutils literal notranslate"><span class="pre">date</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">time</span></code> and all others keys from <code class="docutils literal notranslate"><span class="pre">sar</span></code> data.</p>
+<p>Most common keys are <code class="ansible-value docutils literal notranslate"><span class="pre">ldavg-1</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">ldavg-5</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">ldavg-15</span></code> and others.</p>
+<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> when <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-ans2dev-general-sar-facts-module-parameter-type"><span class="std std-ref"><span class="pre">type</span></span></a></strong></code> is <code class="ansible-value docutils literal notranslate"><span class="pre">load</span></code>.</p>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="return-ansible_facts/sar_mem"></div><p class="ansible-option-title" id="ansible-collections-ans2dev-general-sar-facts-module-return-ansible-facts-sar-mem"><strong>sar_mem</strong></p>
+<a class="ansibleOptionLink" href="#return-ansible_facts/sar_mem" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">dictionary</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Dictionary that contains <code class="docutils literal notranslate"><span class="pre">memory</span></code> data from <code class="docutils literal notranslate"><span class="pre">sar</span></code>.</p>
+<p>It contains <code class="ansible-value docutils literal notranslate"><span class="pre">date</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">time</span></code> and all others keys from <code class="docutils literal notranslate"><span class="pre">sar</span></code> data.</p>
+<p>Most common keys are <code class="ansible-value docutils literal notranslate"><span class="pre">%memused</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">%commit</span></code> and others.</p>
+<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> when <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-ans2dev-general-sar-facts-module-parameter-type"><span class="std std-ref"><span class="pre">type</span></span></a></strong></code> is <code class="ansible-value docutils literal notranslate"><span class="pre">memory</span></code>.</p>
+</div></td>
+</tr>
+<tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="return-ansible_facts/sar_net"></div><p class="ansible-option-title" id="ansible-collections-ans2dev-general-sar-facts-module-return-ansible-facts-sar-net"><strong>sar_net</strong></p>
+<a class="ansibleOptionLink" href="#return-ansible_facts/sar_net" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">dictionary</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Dictionary that contains <code class="docutils literal notranslate"><span class="pre">network</span></code> data from <code class="docutils literal notranslate"><span class="pre">sar</span></code>.</p>
+<p>It contains <code class="ansible-value docutils literal notranslate"><span class="pre">date</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">time</span></code> and all others keys from <code class="docutils literal notranslate"><span class="pre">sar</span></code> data.</p>
+<p>Most common keys are <code class="ansible-value docutils literal notranslate"><span class="pre">IFACE</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">rxpck/s</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">txpck/s</span></code>, v(%ifutil) and others.</p>
+<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> when <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-ans2dev-general-sar-facts-module-parameter-type"><span class="std std-ref"><span class="pre">type</span></span></a></strong></code> is <code class="ansible-value docutils literal notranslate"><span class="pre">network</span></code>.</p>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="return-ansible_facts/sar_swap"></div><p class="ansible-option-title" id="ansible-collections-ans2dev-general-sar-facts-module-return-ansible-facts-sar-swap"><strong>sar_swap</strong></p>
+<a class="ansibleOptionLink" href="#return-ansible_facts/sar_swap" title="Permalink to this return value"></a><p class="ansible-option-type-line"><span class="ansible-option-type">dictionary</span></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Dictionary that contains <code class="docutils literal notranslate"><span class="pre">swap</span></code> data from <code class="docutils literal notranslate"><span class="pre">sar</span></code>.</p>
+<p>It contains <code class="ansible-value docutils literal notranslate"><span class="pre">date</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">time</span></code> and all others keys from <code class="docutils literal notranslate"><span class="pre">sar</span></code> data.</p>
+<p>Most common keys are <code class="ansible-value docutils literal notranslate"><span class="pre">%swpused</span></code>, <code class="ansible-value docutils literal notranslate"><span class="pre">%swpcad</span></code> and others.</p>
+<p class="ansible-option-line"><strong class="ansible-option-returned-bold">Returned:</strong> when <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-ans2dev-general-sar-facts-module-parameter-type"><span class="std std-ref"><span class="pre">type</span></span></a></strong></code> is <code class="ansible-value docutils literal notranslate"><span class="pre">swap</span></code>.</p>
+</div></td>
+</tr>
+</tbody>
+</table>
 <section id="authors">
 <h3>Authors<a class="headerlink" href="#authors" title="Link to this heading"></a></h3>
 <ul class="simple">

[NomakCooper]

/approve

[repo-command]

Pull request approved by @NomakCooper

[patchback]

Backport to stable-10: 💚 backport PR created

✅ Backport PR branch: patchback/backports/stable-10/39defcf1b8e3d488fe40cd4034fdc92c36c7af23/pr-124

Backported as #125

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.