Add 'idempotent' attribute

[felixfontein]

SUMMARY

Adds a new attribute idempotent for module documentation, which states whether (resp. under which circumstances) the module is idempotent.

Related PRs:

• Add 'idempotent' attribute community.dns#238
• Add 'idempotent' attribute community.crypto#833
• Add 'idempotent' attribute community.docker#1022
• Add 'idempotent' attribute community.hrobot#132
• Add 'idempotent' attribute community.routeros#337

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

module documentation

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 83.60%. Comparing base (9f2e345) to head (6f687d9).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #217      +/-   ##
==========================================
+ Coverage   83.58%   83.60%   +0.02%     
==========================================
  Files          12       12              
  Lines         725      726       +1     
  Branches      142      142              
==========================================
+ Hits          606      607       +1     
  Misses         84       84              
  Partials       35       35              

Flag	Coverage Δ
integration	81.71% <ø> (ø)
sanity	29.61% <100.00%> (+0.09%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[github-actions]

Docs Build 📝

Thank you for contribution!✨

The docs for this PR have been published here:
https://ansible-collections.github.io/community.sops/pr/217

You can compare to the docs for the main branch here:
https://ansible-collections.github.io/community.sops/branch/main

The docsite for this PR is also available for download as an artifact from this run:
https://github.com/ansible-collections/community.sops/actions/runs/12550802610

File changes:

• M install_role.html
• M load_vars_module.html
• M sops_encrypt_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/community.sops/community.sops/docsbuild/base/install_role.html b/home/runner/work/community.sops/community.sops/docsbuild/head/install_role.html
index b18ea6f..d4b7771 100644
--- a/home/runner/work/community.sops/community.sops/docsbuild/base/install_role.html
+++ b/home/runner/work/community.sops/community.sops/docsbuild/head/install_role.html
@@ -97,6 +97,7 @@
 <li class="toctree-l2"><a class="reference internal" href="#entry-point-main-install-sops">Entry point <code class="docutils literal notranslate"><span class="pre">main</span></code> – Install SOPS</a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#synopsis">Synopsis</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#parameters">Parameters</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#attributes">Attributes</a></li>
 <li class="toctree-l3"><a class="reference internal" href="#authors">Authors</a><ul>
 <li class="toctree-l4"><a class="reference internal" href="#collection-links">Collection links</a></li>
 </ul>
@@ -151,7 +152,8 @@ To check whether it is installed, run <code class="code docutils literal notrans
 <ul>
 <li><p><a class="reference internal" href="#synopsis" id="id2">Synopsis</a></p></li>
 <li><p><a class="reference internal" href="#parameters" id="id3">Parameters</a></p></li>
-<li><p><a class="reference internal" href="#authors" id="id4">Authors</a></p></li>
+<li><p><a class="reference internal" href="#attributes" id="id4">Attributes</a></p></li>
+<li><p><a class="reference internal" href="#authors" id="id5">Authors</a></p></li>
 </ul>
 </li>
 </ul>
@@ -254,8 +256,58 @@ To check whether it is installed, run <code class="code docutils literal notrans
 </tbody>
 </table>
 </section>
+<section id="attributes">
+<h3><a class="toc-backref" href="#id4" role="doc-backlink">Attributes</a><a class="headerlink" href="#attributes" title="Link to this heading"></a></h3>
+<table class="longtable ansible-option-table docutils align-default" style="width: 100%">
+<thead>
+<tr class="row-odd"><th class="head"><p>Attribute</p></th>
+<th class="head"><p>Support</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="attribute-check_mode"></div><p class="ansible-option-title" id="ansible-collections-community-sops-install-role-attribute-main-check-mode"><strong>check_mode</strong></p>
+<a class="ansibleOptionLink" href="#attribute-check_mode" title="Permalink to this attribute"></a></div></td>
+<td><div class="ansible-option-cell"><p><strong class="ansible-attribute-support-label">Support: </strong><strong class="ansible-attribute-support-none">none</strong></p>
+<p>The role currently does not work in check mode.</p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Can run in <code class="docutils literal notranslate"><span class="pre">check_mode</span></code> and return changed status prediction without modifying target.</p>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="attribute-diff_mode"></div><p class="ansible-option-title" id="ansible-collections-community-sops-install-role-attribute-main-diff-mode"><strong>diff_mode</strong></p>
+<a class="ansibleOptionLink" href="#attribute-diff_mode" title="Permalink to this attribute"></a></div></td>
+<td><div class="ansible-option-cell"><p><strong class="ansible-attribute-support-label">Support: </strong><strong class="ansible-attribute-support-partial">partial</strong></p>
+<p>The role supports diff mode if the <a class="reference external" href="https://docs.ansible.com/ansible/devel/collections/ansible/builtin/package_module.html#ansible-collections-ansible-builtin-package-module" title="(in Ansible vdevel)"><span class="xref std std-ref">ansible.builtin.package</span></a> action for the system supports it.</p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Will return details on what has changed (or possibly needs changing in <code class="docutils literal notranslate"><span class="pre">check_mode</span></code>), when in diff mode.</p>
+</div></td>
+</tr>
+<tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="attribute-idempotent"></div><p class="ansible-option-title" id="ansible-collections-community-sops-install-role-attribute-main-idempotent"><strong>idempotent</strong></p>
+<a class="ansibleOptionLink" href="#attribute-idempotent" title="Permalink to this attribute"></a></div></td>
+<td><div class="ansible-option-cell"><p><strong class="ansible-attribute-support-label">Support: </strong><strong class="ansible-attribute-support-partial">partial</strong></p>
+<p>The role is idempotent if the <a class="reference external" href="https://docs.ansible.com/ansible/devel/collections/ansible/builtin/package_module.html#ansible-collections-ansible-builtin-package-module" title="(in Ansible vdevel)"><span class="xref std std-ref">ansible.builtin.package</span></a> action for the system is idempotent.</p>
+<p>This is usually the case, but if packages need to be installed from GitHub (that is, through an URL), idempotence might not hold.</p>
+</div></td>
+<td><div class="ansible-option-cell"><p>When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.</p>
+<p>This assumes that the system controlled/queried by the module has not changed in a relevant way.</p>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="attribute-platform"></div><p class="ansible-option-title" id="ansible-collections-community-sops-install-role-attribute-main-platform"><strong>platform</strong></p>
+<a class="ansibleOptionLink" href="#attribute-platform" title="Permalink to this attribute"></a></div></td>
+<td><div class="ansible-option-cell"><p><strong class="ansible-attribute-support-property">Platforms:</strong> <strong class="ansible-attribute-support-full">Alpine (new enough)</strong>, <strong class="ansible-attribute-support-full">Arch Linux</strong>, <strong class="ansible-attribute-support-full">CentOS 7, Stream 8, or newer</strong>, <strong class="ansible-attribute-support-full">Debian 10 (Buster) or newer</strong>, <strong class="ansible-attribute-support-full">Fedora (new enough)</strong>, <strong class="ansible-attribute-support-full">RHEL 7 or newer</strong>, <strong class="ansible-attribute-support-full">Ubuntu 16.04 or newer LTS versions</strong></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Target OS/families that can be operated against.</p>
+</div></td>
+</tr>
+</tbody>
+</table>
+</section>
 <section id="authors">
-<h3><a class="toc-backref" href="#id4" role="doc-backlink">Authors</a><a class="headerlink" href="#authors" title="Link to this heading"></a></h3>
+<h3><a class="toc-backref" href="#id5" role="doc-backlink">Authors</a><a class="headerlink" href="#authors" title="Link to this heading"></a></h3>
 <ul class="simple">
 <li><p>Felix Fontein (&#64;felixfontein)</p></li>
 </ul>
diff --git a/home/runner/work/community.sops/community.sops/docsbuild/base/load_vars_module.html b/home/runner/work/community.sops/community.sops/docsbuild/head/load_vars_module.html
index bc4fda3..21b7eef 100644
--- a/home/runner/work/community.sops/community.sops/docsbuild/base/load_vars_module.html
+++ b/home/runner/work/community.sops/community.sops/docsbuild/head/load_vars_module.html
@@ -375,6 +375,16 @@ see <a class="reference internal" href="#ansible-collections-community-sops-load
 <td><div class="ansible-option-cell"><p>Action returns an <code class="docutils literal notranslate"><span class="pre">ansible_facts</span></code> dictionary that will update existing host facts.</p>
 </div></td>
 </tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="attribute-idempotent"></div><p class="ansible-option-title" id="ansible-collections-community-sops-load-vars-module-attribute-idempotent"><strong>idempotent</strong></p>
+<a class="ansibleOptionLink" href="#attribute-idempotent" title="Permalink to this attribute"></a></div></td>
+<td><div class="ansible-option-cell"><p><strong class="ansible-attribute-support-label">Support: </strong>      <span class="ansible-attribute-support-na">N/A</span></p>
+<p>The action has no <code class="docutils literal notranslate"><span class="pre">changed</span></code> state.</p>
+</div></td>
+<td><div class="ansible-option-cell"><p>When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.</p>
+<p>This assumes that the system controlled/queried by the module has not changed in a relevant way.</p>
+</div></td>
+</tr>
 </tbody>
 </table>
 </section>
diff --git a/home/runner/work/community.sops/community.sops/docsbuild/base/sops_encrypt_module.html b/home/runner/work/community.sops/community.sops/docsbuild/head/sops_encrypt_module.html
index ee3fe53..8c6f322 100644
--- a/home/runner/work/community.sops/community.sops/docsbuild/base/sops_encrypt_module.html
+++ b/home/runner/work/community.sops/community.sops/docsbuild/head/sops_encrypt_module.html
@@ -570,6 +570,15 @@ see <a class="reference internal" href="#ansible-collections-community-sops-sops
 </div></td>
 </tr>
 <tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="attribute-idempotent"></div><p class="ansible-option-title" id="ansible-collections-community-sops-sops-encrypt-module-attribute-idempotent"><strong>idempotent</strong></p>
+<a class="ansibleOptionLink" href="#attribute-idempotent" title="Permalink to this attribute"></a></div></td>
+<td><div class="ansible-option-cell"><p><strong class="ansible-attribute-support-label">Support: </strong><strong class="ansible-attribute-support-full">full</strong></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>When run twice in a row outside check mode, with the same arguments, the second invocation indicates no change.</p>
+<p>This assumes that the system controlled/queried by the module has not changed in a relevant way.</p>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="attribute-safe_file_operations"></div><p class="ansible-option-title" id="ansible-collections-community-sops-sops-encrypt-module-attribute-safe-file-operations"><strong>safe_file_operations</strong></p>
 <a class="ansibleOptionLink" href="#attribute-safe_file_operations" title="Permalink to this attribute"></a></div></td>
 <td><div class="ansible-option-cell"><p><strong class="ansible-attribute-support-label">Support: </strong><strong class="ansible-attribute-support-full">full</strong></p>