mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
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>
This commit is contained in:
parent
58ce19d2c2
commit
5a5188a453
3 changed files with 79 additions and 0 deletions
2
.github/BOTMETA.yml
vendored
2
.github/BOTMETA.yml
vendored
|
@ -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
|
||||
#########################
|
||||
|
|
|
@ -14,3 +14,6 @@ sections:
|
|||
- guide_online
|
||||
- guide_packet
|
||||
- guide_scaleway
|
||||
- title: Developer Guides
|
||||
toctree:
|
||||
- guide_deps
|
||||
|
|
74
docs/docsite/rst/guide_deps.rst
Normal file
74
docs/docsite/rst/guide_deps.rst
Normal file
|
@ -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
|
Loading…
Reference in a new issue