From 4d34ad999a1e8f8d2a8f3cdb46af0340ff0e6541 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Mei=C3=9Fner?= Date: Mon, 30 Oct 2023 12:53:47 +0100 Subject: [PATCH] Made some doc and test changes (#114) - Add separate section for folder tests Because of codeaffen/phpipam-ansible-modules#107 we added a separate section which will be created before running folder tests. Test variables will be linked to that new section via jinja templating. After running tests the section will be deleted. - update folder module doc - add filter doc source - remove old filter documentation - remove docs for non-existing lookup module - create fresh filter doc --- docs/filters.rst | 15 -- docs/index.rst | 1 - docs/plugins/folder_module.rst | 5 + docs/plugins/index.rst | 2 +- docs/plugins/is_subnet_filter.rst | 289 ++++++++++++++++++++++++- docs/plugins/subnet_lookup.rst | 285 ------------------------ plugins/filter/is_subnet.py | 28 +++ plugins/modules/folder.py | 3 + tests/test_playbooks/folder.yml | 14 ++ tests/test_playbooks/folder_parent.yml | 14 ++ tests/test_playbooks/vars/folder.yml | 11 +- 11 files changed, 351 insertions(+), 316 deletions(-) delete mode 100644 docs/filters.rst delete mode 100644 docs/plugins/subnet_lookup.rst create mode 100644 plugins/filter/is_subnet.py diff --git a/docs/filters.rst b/docs/filters.rst deleted file mode 100644 index 0d930bf..0000000 --- a/docs/filters.rst +++ /dev/null @@ -1,15 +0,0 @@ -Filters -======= - -Filters are used to manipulate data if needed. - -is_subnet ---------- - -This filter checks whether a given subnet belongs to the second one. It returns `true` if first subnet belongs to the second and `false` if not, or if both subnets are the same. - -**since version:** 1.2.0 - -.. code-block:: yaml - - 192.0.2.0/25 | codeaffen.phpipam.is_subnet(192.0.2.0/24) diff --git a/docs/index.rst b/docs/index.rst index 3a7ff00..905553f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,7 +13,6 @@ Welcome to phpIPAM Ansible Module documentation! README Changelog plugins/index - Filters .. toctree:: :maxdepth: 2 diff --git a/docs/plugins/folder_module.rst b/docs/plugins/folder_module.rst index 14c9ed5..1e03fd9 100644 --- a/docs/plugins/folder_module.rst +++ b/docs/plugins/folder_module.rst @@ -461,6 +461,11 @@ Parameters .. Notes +Notes +----- + +.. note:: + - This module needs a phpIPAM backend with version 1.4.1 or highter. .. Seealso diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst index 6689fe1..cb3bb36 100644 --- a/docs/plugins/index.rst +++ b/docs/plugins/index.rst @@ -96,7 +96,7 @@ Modules Filter Plugins ~~~~~~~~~~~~~~ -* :ansplugin:`is_subnet filter ` -- +* :ansplugin:`is_subnet filter ` -- Check if a subnet belongs to another .. toctree:: :maxdepth: 1 diff --git a/docs/plugins/is_subnet_filter.rst b/docs/plugins/is_subnet_filter.rst index 067834a..df9f7cf 100644 --- a/docs/plugins/is_subnet_filter.rst +++ b/docs/plugins/is_subnet_filter.rst @@ -1,30 +1,299 @@ -.. Document meta section +.. Document meta :orphan: +.. |antsibull-internal-nbsp| unicode:: 0xA0 + :trim: + .. meta:: :antsibull-docs: 2.5.0 -.. Document body - .. Anchors .. _ansible_collections.codeaffen.phpipam.is_subnet_filter: +.. Anchors: short name for ansible.builtin + .. Title -codeaffen.phpipam.is_subnet filter -++++++++++++++++++++++++++++++++++ +codeaffen.phpipam.is_subnet filter -- Check if a subnet belongs to another +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +.. Collection note + +.. note:: + This filter plugin is part of the `codeaffen.phpipam collection `_ (version 1.7.0). + + It is not included in ``ansible-core``. + To check whether it is installed, run :code:`ansible-galaxy collection list`. + + To install it, use: :code:`ansible-galaxy collection install codeaffen.phpipam`. + + To use it in a playbook, specify: :code:`codeaffen.phpipam.is_subnet`. + +.. version_added + +.. rst-class:: ansible-version-added + +New in codeaffen.phpipam 1.2.0 + +.. contents:: + :local: + :depth: 1 + +.. Deprecated + + +Synopsis +-------- + +.. Description + +- First argument is a subnet second another. If the first subnet belongs to second + + +.. Aliases + + +.. Requirements + + + + + +.. Input + +Input +----- + +This describes the input of the filter, the value before ``| codeaffen.phpipam.is_subnet``. + +.. tabularcolumns:: \X{1}{3}\X{2}{3} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Parameter + - Comments + + * - .. raw:: html + +
+
+ + .. _ansible_collections.codeaffen.phpipam.is_subnet_filter__parameter-_input: + + .. rst-class:: ansible-option-title + + **Input** + + .. raw:: html + + + + .. ansible-option-type-line:: + + :ansible-option-type:`string` / :ansible-option-required:`required` + + + + + .. raw:: html + +
+ + - .. raw:: html + +
+ + Subnet in cidr format which should belongs to parent + + + .. raw:: html + +
+ + + + +.. Positional + +Positional parameters +--------------------- + +This describes positional parameters of the filter. These are the values ``positional1``, ``positional2`` and so on in the following +example: ``input | codeaffen.phpipam.is_subnet(positional1, positional2, ...)`` + +.. tabularcolumns:: \X{1}{3}\X{2}{3} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Parameter + - Comments + + * - .. raw:: html + +
+
+ + .. _ansible_collections.codeaffen.phpipam.is_subnet_filter__parameter-parent: + + .. rst-class:: ansible-option-title + + **parent** + + .. raw:: html + + + + .. ansible-option-type-line:: + + :ansible-option-type:`string` / :ansible-option-required:`required` + + + + + .. raw:: html + +
+ + - .. raw:: html + +
+ + Subnet where input should belongs to + + + .. raw:: html + +
+ + + +.. Options + + +.. Attributes + + +.. Notes + + +.. Seealso + + +.. Examples + +Examples +-------- + +.. code-block:: yaml+jinja + + + 192.0.2.0/25 | codeaffen.phpipam.is_subnet(192.0.2.0/24) + + + + +.. Facts + + +.. Return values + +Return Value +------------ + +.. tabularcolumns:: \X{1}{3}\X{2}{3} + +.. list-table:: + :width: 100% + :widths: auto + :header-rows: 1 + :class: longtable ansible-option-table + + * - Key + - Description + + * - .. raw:: html + +
+
+ + .. _ansible_collections.codeaffen.phpipam.is_subnet_filter__return-_value: + + .. rst-class:: ansible-option-title + + **Return value** + + .. raw:: html + + + + .. ansible-option-type-line:: + + :ansible-option-type:`boolean` + + .. raw:: html + +
+ + - .. raw:: html + +
+ + True if children belongs to parent and false if not or both networks are the same. + + + .. rst-class:: ansible-option-line + + :ansible-option-returned-bold:`Returned:` success + + + .. raw:: html + +
+ + + +.. Status (Presently only deprecated) + + +.. Authors + +Authors +~~~~~~~ + +- Christian Meißner + + +.. hint:: + Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up. +.. Extra links -The documentation for the filter plugin, codeaffen.phpipam.is_subnet, was malformed. +Collection links +~~~~~~~~~~~~~~~~ -The errors were: +.. ansible-links:: -* :: + - title: "Issue Tracker" + url: "https://github.com/codeaffen/phpipam-ansible-modules/issues" + external: true + - title: "Homepage" + url: "https://codeaffen.org/projects/phpipam-ansible-modules" + external: true + - title: "Repository (Sources)" + url: "https://github.com/codeaffen/phpipam-ansible-modules" + external: true - Missing documentation or could not parse documentation: No documentation available for codeaffen.phpipam.is_subnet (/home/cme/Development/github/cmeissner/phpipam-ansible-modules/build/collections/ansible_collections/codeaffen/phpipam/plugins/filter/phpipam.py) +.. Parsing errors -File a bug with the `codeaffen.phpipam collection `_ in order to have it corrected. \ No newline at end of file diff --git a/docs/plugins/subnet_lookup.rst b/docs/plugins/subnet_lookup.rst deleted file mode 100644 index b9c2690..0000000 --- a/docs/plugins/subnet_lookup.rst +++ /dev/null @@ -1,285 +0,0 @@ -.. Document meta - -:orphan: - -.. |antsibull-internal-nbsp| unicode:: 0xA0 - :trim: - -.. role:: ansible-attribute-support-label -.. role:: ansible-attribute-support-property -.. role:: ansible-attribute-support-full -.. role:: ansible-attribute-support-partial -.. role:: ansible-attribute-support-none -.. role:: ansible-attribute-support-na - -.. Anchors - -.. _ansible_collections.codeaffen.phpipam.subnet_lookup: - -.. Anchors: short name for ansible.builtin - -.. Anchors: aliases - - - -.. Title - -codeaffen.phpipam.subnet -- lookup for subnet information -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -.. Collection note - -.. note:: - This plugin is part of the `codeaffen.phpipam collection `_ (version 1.5.0). - - You might already have this collection installed if you are using the ``ansible`` package. - It is not included in ``ansible-core``. - To check whether it is installed, run :code:`ansible-galaxy collection list`. - - To install it, use: :code:`ansible-galaxy collection install codeaffen.phpipam`. - - To use it in a playbook, specify: :code:`codeaffen.phpipam.subnet`. - -.. version_added - -.. versionadded:: 1.5.0 of codeaffen.phpipam - -.. contents:: - :local: - :depth: 1 - -.. Deprecated - - -Synopsis --------- - -.. Description - -- This lookup returns information about a subnet. - - -.. Aliases - - -.. Requirements - - -.. Options - -Parameters ----------- - -.. raw:: html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ParameterChoices/DefaultsConfigurationComments
-
- _terms - -
- string - / required
- - 		- - -
Subnet in CIDR notation
-
-
- app_id - -
- string -
- - 		- -
ini entries: -

- [phpipam]
app_id = None - -

-
-
- env:PHPIPAM_APPID - -
- 		-
Application ID
-
-
- password - -
- string -
- - 		- -
ini entries: -

- [phpipam]
password = None - -

-
-
- env:PHPIPAM_PASSWORD - -
- 		-
Password to authenticate with the server
-
-
- url - -
- string -
- - 		- -
ini entries: -

- [phpipam]
url = None - -

-
-
- env:PHPIPAM_URL - -
- 		-
URL of the server to query
-
-
- username - -
- string -
- - 		- -
ini entries: -

- [phpipam]
username = None - -

-
-
- env:PHPIPAM_USERNAME - -
- 		-
Username to authenticate with the server
-
-
- verify_ssl - -
- boolean -
- - 		-
    Choices: -
  • no
    • -
  • yes ←
    • -
- 		-
ini entries: -

- [phpipam]
verify_ssl = yes - -

-
-
- env:PHPIPAM_VERIFY_SSL - -
- 		-
Whether to verify SSL certificates
-
-
- -.. Attributes - - -.. Notes - -Notes ------ - -.. note:: - - This lookup requires the ipaddress module. - - This lookup returns a list of ip addresses. - -.. Seealso - - -.. Examples - - - -.. Facts - - -.. Return values - - -.. Status (Presently only deprecated) - - -.. Authors - -Authors -~~~~~~~ - -- Christian Meißner (@cmeissner) - - - -.. Parsing errors - diff --git a/plugins/filter/is_subnet.py b/plugins/filter/is_subnet.py new file mode 100644 index 0000000..179de41 --- /dev/null +++ b/plugins/filter/is_subnet.py @@ -0,0 +1,28 @@ +DOCUMENTATION = r''' + name: is_subnet + author: Christian Meißner + version_added: '1.2.0' + short_description: Check if a subnet belongs to another + description: + - First argument is a subnet second another. If the first subnet belongs to second + positional: _input, parent + options: + _input: + description: Subnet in cidr format which should belongs to parent + type: string + required: true + parent: + description: Subnet where input should belongs to + type: string + required: true +''' + +EXAMPLES = r''' + 192.0.2.0/25 | codeaffen.phpipam.is_subnet(192.0.2.0/24) +''' + +RETURN = r''' + _value: + description: True if children belongs to parent and false if not or both networks are the same. + type: bool +''' diff --git a/plugins/modules/folder.py b/plugins/modules/folder.py index af45c01..a047484 100644 --- a/plugins/modules/folder.py +++ b/plugins/modules/folder.py @@ -27,6 +27,9 @@ - create, update and delete folders author: - "Christian Meißner (@cmeissner)" +notes: + - This module needs a phpIPAM backend with version 1.4.1 or highter. + options: name: description: Name of the folder to manage diff --git a/tests/test_playbooks/folder.yml b/tests/test_playbooks/folder.yml index 190d211..bba15e9 100644 --- a/tests/test_playbooks/folder.yml +++ b/tests/test_playbooks/folder.yml @@ -5,6 +5,12 @@ - vars/server.yml - vars/folder.yml tasks: + - name: Create Section + ansible.builtin.include_tasks: tasks/section.yml + vars: + step: Create empty section for folder tests + section: '{{ folder_section }}' + - name: Create folder ansible.builtin.include_tasks: tasks/folder.yml vars: @@ -22,3 +28,11 @@ override: state: absent folder: '{{ base_folder_data | combine(override) }}' + + - name: Delete Section + ansible.builtin.include_tasks: tasks/section.yml + vars: + step: delete folder tests section + override: + state: absent + section: '{{ folder_section | combine(override) }}' diff --git a/tests/test_playbooks/folder_parent.yml b/tests/test_playbooks/folder_parent.yml index ea5aeaf..ef6854d 100644 --- a/tests/test_playbooks/folder_parent.yml +++ b/tests/test_playbooks/folder_parent.yml @@ -5,6 +5,12 @@ - vars/server.yml - vars/folder.yml tasks: + - name: Create Section + ansible.builtin.include_tasks: tasks/section.yml + vars: + step: Create empty section for folder tests + section: '{{ folder_section }}' + - name: Create parent/children folders ansible.builtin.include_tasks: tasks/folder.yml vars: @@ -29,3 +35,11 @@ loop: '{{ folder_parents }}' loop_control: loop_var: folder_loop + + - name: Delete Section + ansible.builtin.include_tasks: tasks/section.yml + vars: + step: delete folder tests section + override: + state: absent + section: '{{ folder_section | combine(override) }}' diff --git a/tests/test_playbooks/vars/folder.yml b/tests/test_playbooks/vars/folder.yml index 41517ff..e3ac350 100644 --- a/tests/test_playbooks/vars/folder.yml +++ b/tests/test_playbooks/vars/folder.yml @@ -1,14 +1,17 @@ --- +folder_section: + name: "Folder Test Section" + base_folder_data: name: Example folder - section: "Customers" + section: "{{ folder_section.name }}" folder_parents: - name: Parent folder - section: "Customers" + section: "{{ folder_section.name }}" - name: Sub folder 1 parent: Parent folder - section: "Customers" + section: "{{ folder_section.name }}" - name: Sub folder 2 - section: "Customers" + section: "{{ folder_section.name }}" parent: Parent folder