added contributing information

CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contribute
+
+Thank you for considering to contribute to this project!
+
+## What to contribute
+
+* report errors as [issues](https://github.com/ansibleguy/collection_opnsense/issues)
+* test unstable modules and [report if they work as expected](https://github.com/ansibleguy/collection_opnsense/discussions/new?category=general)
+* add [ansible-based tests](https://github.com/ansibleguy/collection_opnsense/blob/latest/tests) for some error-case(s) you have encountered
+* extend or correct the [documentation](https://github.com/ansibleguy/collection_opnsense/blob/latest/docs)
+* add missing inline documentation [as standardized](https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#documentation-block)
+  * should be placed in `<COLLECTION>/plugins/module_utils/inline_docs/<MODULE>.py` and then imported in the module
+* contribute code fixes or optimizations
+* implement additional API endpoints/modules
+
+## Module development
+
+See: [Documentation - Development](https://opnsense.ansibleguy.net/en/latest/usage/4_develop.html)

README.md

@@ -42,13 +42,7 @@ See: [Docs](https://opnsense.ansibleguy.net)
 
 Feel free to contribute to this project using [pull-requests](https://github.com/ansibleguy/collection_opnsense/pulls), [issues](https://github.com/ansibleguy/collection_opnsense/issues) and [discussions](https://github.com/ansibleguy/collection_opnsense/discussions)!
 
-**What to contribute**:
-
-* add ansible-based [tests](https://github.com/ansibleguy/collection_opnsense/blob/latest/tests) for some error-case(s) you have encountered
-* extend or correct the [documentation](https://github.com/ansibleguy/collection_opnsense/blob/latest/docs)
-* contribute code fixes or optimizations
-* implement additional API endpoints => see [development guide](https://opnsense.ansibleguy.net/en/latest/usage/4_develop.html)
-* test unstable modules and report bugs/errors
+See also: [Contributing](https://github.com/ansibleguy/collection_opnsense/blob/latest/CONTRIBUTING.md)
 
 ----
 
@@ -58,10 +52,6 @@ Feel free to contribute to this project using [pull-requests](https://github.com
 
 not implemented => development => [testing](https://github.com/ansibleguy/collection_opnsense/tree/latest/tests) => unstable (_practical testing_) => stable
 
-### Roadmap poll
-
-Choose what modules YOU would find useful: [Roadmap Poll](https://github.com/ansibleguy/collection_opnsense/discussions/14)
-
 ### Implemented
 
 
@@ -88,13 +78,13 @@ Choose what modules YOU would find useful: [Roadmap Poll](https://github.com/ans
 | **DNS**             | ansibleguy.opnsense.unbound_domain                                     | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/unbound_domain.html)                                     | stable   |
 | **DNS**             | ansibleguy.opnsense.unbound_host_alias                                 | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/unbound_host_alias.html)                                 | stable |
 | **Syslog**          | ansibleguy.opnsense.syslog                                             | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/syslog.html)                                             | stable   |
-| **IPSec**           | ansibleguy.opnsense.ipsec_connection, ansibleguy.opnsense.ipsec_tunnel | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | unstable |
-| **IPSec**           | ansibleguy.opnsense.ipsec_pool, ansibleguy.opnsense.ipsec_network      | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | unstable |
-| **IPSec**           | ansibleguy.opnsense.ipsec_auth_local                                   | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | unstable |
-| **IPSec**           | ansibleguy.opnsense.ipsec_auth_remote                                  | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | unstable |
-| **IPSec**           | ansibleguy.opnsense.ipsec_child                                        | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | unstable |
-| **IPSec**           | ansibleguy.opnsense.ipsec_vti                                          | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | unstable |
-| **IPSec**           | ansibleguy.opnsense.ipsec_cert                                         | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | unstable |
+| **IPSec**           | ansibleguy.opnsense.ipsec_connection, ansibleguy.opnsense.ipsec_tunnel | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | stable |
+| **IPSec**           | ansibleguy.opnsense.ipsec_pool, ansibleguy.opnsense.ipsec_network      | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | stable |
+| **IPSec**           | ansibleguy.opnsense.ipsec_auth_local                                   | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | stable |
+| **IPSec**           | ansibleguy.opnsense.ipsec_auth_remote                                  | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | stable |
+| **IPSec**           | ansibleguy.opnsense.ipsec_child                                        | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | stable |
+| **IPSec**           | ansibleguy.opnsense.ipsec_vti                                          | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | stable |
+| **IPSec**           | ansibleguy.opnsense.ipsec_cert                                         | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/ipsec.html)                                              | stable |
 | **Traffic Shaper**  | ansibleguy.opnsense.shaper_pipe                                        | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/shaper.html)                                             | stable |
 | **Traffic Shaper**  | ansibleguy.opnsense.shaper_queue                                       | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/shaper.html)                                             | stable |
 | **Traffic Shaper**  | ansibleguy.opnsense.shaper_rule                                        | [Docs](https://opnsense.ansibleguy.net/en/latest/modules/shaper.html)                                             | stable |

docs/source/_tmpl/module_template.rst

@@ -0,0 +1,77 @@
+.. _modules_<module>:
+
+.. include:: ../_include/head.rst
+
+============
+MODULE TITLE
+============
+
+**STATE**: unstable
+
+**TESTS**: `Playbook <https://github.com/ansibleguy/collection_opnsense/blob/latest/tests/<module>.yml>`_
+
+**API Docs**: `<module> <https://docs.opnsense.org/development/api/core/<module>.html>`_
+
+**Service Docs**: `<module> <https://docs.opnsense.org/manual/<module>.html>`_
+
+
+Definition
+**********
+
+..  csv-table:: Definition
+    :header: "Parameter", "Type", "Required", "Default", "Aliases", "Comment"
+    :widths: 15 10 10 10 10 45
+
+    "parameter name","parameter type","if is required","default value","aliases","description"
+    "placeholder","string","false","\-","\-","Some description"
+    "reload","boolean","false","true","\-", .. include:: ../_include/param_reload.rst
+
+.. include:: ../_include/param_basic.rst
+
+Usage
+*****
+
+Basic description of the module.
+
+Place for additional information the user should know of.
+
+Examples
+********
+
+.. code-block:: yaml
+
+    - hosts: localhost
+      gather_facts: false
+      module_defaults:
+        group/ansibleguy.opnsense.all:
+          firewall: 'opnsense.template.ansibleguy.net'
+          api_credential_file: '/home/guy/.secret/opn.key'
+
+        ansibleguy.opnsense.list:
+          target: '<module>'
+
+      tasks:
+        # add optional parameters commented-out
+        # required ones normally
+        # add their default values to get a brief overview of how the module works
+        - name: Example
+          ansibleguy.opnsense.<module>:
+            description: 'test1'
+            command: 'system remote backup'
+            # state: 'absent'
+            # debug: false
+
+        - name: Adding something
+          ansibleguy.opnsense.<module>:
+
+        - name: Changing something
+          ansibleguy.opnsense.<module>:
+
+        - name: Listing jobs
+          ansibleguy.opnsense.list:
+          #  target: '<module>'
+          register: existing_jobs
+
+        - name: Printing
+          ansible.builtin.debug:
+            var: existing_jobs.data

docs/source/usage/4_develop.rst

@@ -31,10 +31,65 @@ There are `module-templates <https://github.com/ansibleguy/collection_opnsense/b
 Adding new module
 *****************
 
+**Checklist**:
+
+- Create the module-file at:
+  '<COLLECTION>/plugins/modules/<MODULE>.py'
+  You can copy the template from '<COLLECTION>/plugins/modules/_tmpl_obj.py'
+
+- For most modules you should create a sub-file to handle the actual logic so the main module-file is kept clean:
+  '<COLLECTION>/plugins/module_utils/main/<MODULE>.py'
+  You can copy the template from '<COLLECTION>/plugins/module_utils/main/_tmpl.py'
+
+- Add **ansible-based tests**:
+
+  I personally like to write tests before adding new modules and testing the modules functionality from the start (test-driven-development)
+
+  - You can copy the template from '<COLLECTION>/tests/_tmpl.yml'
+
+    Rename all calls to the new module.
+
+  - Add a cleanup-task in '<COLLECTION>/tests/cleanup.yml' (set state we will expect when re-running the tests)
+
+  - Enable the test once it runs successfully - add it to '<COLLECTION>/scripts/test.sh'
+
+
+- Add **documentation**:
+
+  - You can copy the template from '<COLLECTION>/docs/source/_tmpl/module_template.rst' and replace '<module>' and links
+
+    `reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ is preferred, but markdown is also supported
+
+    Also add important module-specific information.
+
+  - Optional: We should also add **inline module-documentation** `as standardized for Ansible <https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#documentation-block>`_
+
+    To keep the main module file clean - the documentation should be placed in '<COLLECTION>/plugins/module_utils/inline_docs/'
+
+    You can copy the template from '<COLLECTION>/plugins/module_utils/inline_docs/_tmpl.py'
+
+    You can then import the documentation inside the main module file.
+
+- Add the module to '<COLLECTION>/meta/runtime.yml'
+
+- Add the module as option to the 'ansibleguy.opnsense.list' module:
+
+  '<COLLECTION>/plugins/modules/list.py'
+
+- Add the module as option to the 'ansibleguy.opnsense.reload' module:
+
+  '<COLLECTION>/plugins/modules/reload.py'
+
+- If you are implementing a new service:
+
+  Add the service as option to the 'ansibleguy.opnsense.service' module:
+
+  '<COLLECTION>/plugins/modules/service.py'
+
+
 Testing
 =======
 
-Copy the test-template '_tmpl.yml' and rename all calls to the new module.
 
 Run the tests like this:
 

plugins/module_utils/inline_docs/_tmpl.py

@@ -0,0 +1,13 @@
+# docs as described here: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_documenting.html#module-format-and-documentation
+
+DOCUMENTATION = r''''
+
+'''
+
+EXAMPLES = r'''
+
+'''
+
+RETURN = r'''
+
+'''