From 5a5188a45338ba7e5631d47f43102ab08c77d874 Mon Sep 17 00:00:00 2001
From: Alexei Znamensky <103110+russoz@users.noreply.github.com>
Date: Sun, 2 Jun 2024 10:16:53 +1200
Subject: [PATCH] deps module_utils: add docs  (#8417)

* add docs for the deps module utils

* wordsmithing

* fix reference and filename

* add entries to BOTMETA.yml

* Update docs/docsite/rst/moddev_guide_deps.rst

Co-authored-by: Felix Fontein <felix@fontein.de>

* adjust docs organisation

* adjust docs organisation II

* PR adjustments

---------

Co-authored-by: Felix Fontein <felix@fontein.de>
---
 .github/BOTMETA.yml             |  2 +
 docs/docsite/extra-docs.yml     |  3 ++
 docs/docsite/rst/guide_deps.rst | 74 +++++++++++++++++++++++++++++++++
 3 files changed, 79 insertions(+)
 create mode 100644 docs/docsite/rst/guide_deps.rst

diff --git a/.github/BOTMETA.yml b/.github/BOTMETA.yml
index ef10a32e0f..7f98718772 100644
--- a/.github/BOTMETA.yml
+++ b/.github/BOTMETA.yml
@@ -1456,6 +1456,8 @@ files:
     maintainers: baldwinSPC nurfet-becirevic t0mk teebes
   docs/docsite/rst/guide_scaleway.rst:
     maintainers: $team_scaleway
+  docs/docsite/rst/guide_deps.rst:
+    maintainers: russoz
   docs/docsite/rst/test_guide.rst:
     maintainers: felixfontein
 #########################
diff --git a/docs/docsite/extra-docs.yml b/docs/docsite/extra-docs.yml
index 529573606c..6b1d53ccd5 100644
--- a/docs/docsite/extra-docs.yml
+++ b/docs/docsite/extra-docs.yml
@@ -14,3 +14,6 @@ sections:
       - guide_online
       - guide_packet
       - guide_scaleway
+  - title: Developer Guides
+    toctree:
+      - guide_deps
diff --git a/docs/docsite/rst/guide_deps.rst b/docs/docsite/rst/guide_deps.rst
new file mode 100644
index 0000000000..4c0c4687a4
--- /dev/null
+++ b/docs/docsite/rst/guide_deps.rst
@@ -0,0 +1,74 @@
+..
+  Copyright (c) Ansible Project
+  GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+  SPDX-License-Identifier: GPL-3.0-or-later
+
+.. _ansible_collections.community.general.docsite.guide_deps:
+
+``deps`` Guide
+==============
+
+
+Using ``deps``
+^^^^^^^^^^^^^^
+
+The ``ansible_collections.community.general.plugins.module_utils.deps`` module util simplifies
+the importing of code as described in :ref:`Importing and using shared code <shared_code>`.
+Please notice that ``deps`` is meant to be used specifically with Ansible modules, and not other types of plugins.
+
+The same example from the Developer Guide would become:
+
+.. code-block:: python
+
+    from ansible_collections.community.general.plugins.module_utils import deps
+
+    with deps.declare("foo"):
+        import foo
+
+Then in ``main()``, just after the argspec (or anywhere in the code, for that matter), do
+
+.. code-block:: python
+
+    deps.validate(module)  # assuming module is a valid AnsibleModule instance
+
+By default, ``deps`` will rely on ``ansible.module_utils.basic.missing_required_lib`` to generate
+a message about a failing import. That function accepts parameters ``reason`` and ``url``, and
+and so does ``deps```:
+
+.. code-block:: python
+
+    with deps.declare("foo", reason="foo is needed to properly bar", url="https://foo.bar.io"):
+        import foo
+
+If you would rather write a custom message instead of using ``missing_required_lib`` then do:
+
+.. code-block:: python
+
+    with deps.declare("foo", msg="Custom msg explaining why foo is needed"):
+        import foo
+
+``deps`` allows for multiple dependencies to be declared:
+
+.. code-block:: python
+
+    with deps.declare("foo"):
+        import foo
+
+    with deps.declare("bar"):
+        import bar
+
+    with deps.declare("doe"):
+        import doe
+
+By default, ``deps.validate()`` will check on all the declared dependencies, but if so desired,
+they can be validated selectively by doing:
+
+.. code-block:: python
+
+    deps.validate(module, "foo")       # only validates the "foo" dependency
+
+    deps.validate(module, "doe:bar")   # only validates the "doe" and "bar" dependencies
+
+    deps.validate(module, "-doe:bar")  # validates all dependencies except "doe" and "bar"
+
+.. versionadded:: 6.1.0