diff --git a/docs/docsite/rst/community/contributing_maintained_collections.rst b/docs/docsite/rst/community/contributing_maintained_collections.rst index f508d145f97..27778e2e63c 100644 --- a/docs/docsite/rst/community/contributing_maintained_collections.rst +++ b/docs/docsite/rst/community/contributing_maintained_collections.rst @@ -217,6 +217,18 @@ The following table shows: ✓ Network guide + + vmware.vmware_rest + + Network + ✓ + ✓ + ✓ + Zuul + ✓ + VMWare REST guide + + diff --git a/docs/docsite/rst/dev_guide/index.rst b/docs/docsite/rst/dev_guide/index.rst index c4aea0a16e2..f372e3075c9 100644 --- a/docs/docsite/rst/dev_guide/index.rst +++ b/docs/docsite/rst/dev_guide/index.rst @@ -74,6 +74,7 @@ If you prefer to read the entire guide, here's a list of the pages in order. platforms/openstack_guidelines platforms/ovirt_dev_guide platforms/vmware_guidelines + platforms/vmware_rest_guidelines developing_modules_in_groups testing module_lifecycle diff --git a/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst b/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst new file mode 100644 index 00000000000..17bfd3fdcc3 --- /dev/null +++ b/docs/docsite/rst/dev_guide/platforms/vmware_rest_guidelines.rst @@ -0,0 +1,111 @@ +.. _VMware_REST_module_development: + +********************************************* +Guidelines for VMware REST module development +********************************************* + +The Ansible VMware REST collection (on `Galaxy `_, source code `repository `_) is maintained by Red Hat and the community. + +.. contents:: + :local: + +Contribution process +==================== + +The modules of the vmware_rest collection are autogenerated by another tool called `vmware_rest_code_generator `. + +If you would like to contribute a change, we would appreciate if you: + +- submit a Github Pull Request (PR) against the vmware_rest_code_generator project +- but also ensure the generated modules are compliant with our quality criterias. + +Requirements +============ + +You will need: + +- Python 3.6 or greater +- the `tox ` command + + +vmware_rest_code_generator +========================== + +Your contribution should follow the coding style of `Black `. +To run the code formatter, just run: + +.. code-block:: shell + + tox -e black + +To regenerate the vmware_rest collection, you can use the following commands: + +.. code-block:: shell + + tox -e refresh_modules -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest + +If you also want to update the EXAMPLE section of the modules, run: + +.. code-block:: shell + + tox -e refresh_examples -- --target-dir ~/.ansible/collections/ansible_collections/vmware/vmware_rest + +Testing with ansible-test +========================= + +All the modules are covered by a functional test. The tests are located in the :file:`tests/integration/targets/`. + +To run the tests, you will need a vcenter instance and an ESXi. + +black code formatter +~~~~~~~~~~~~~~~~~~~~ + +We follow the coding style of `Black `. +You can run the code formatter with the following command. + + +.. code-block:: shell + + tox -e black + +sanity tests +~~~~~~~~~~~~ + +Here we use Python 3.8, the minimal version is 3.6. + +.. code-block:: shell + + tox -e black + ansible-test sanity --debug --requirements --local --skip-test future-import-boilerplate --skip-test metaclass-boilerplate --python 3.8 -vvv + + +integration tests +~~~~~~~~~~~~~~~~~ + +These tests should be run against your test environment. + +..warning:: The test suite will delete all the existing DC from your test environment. + +First, prepare a configuration file, we call it :file:`/tmp/inventory-vmware_rest` in +this example: + +.. code-block:: ini + + [vmware_rest] + localhost ansible_connection=local ansible_python_interpreter=python + + [vmware_rest:vars] + vcenter_hostname=vcenter.test + vcenter_username=administrator@vsphere.local + vcenter_password=kLRy|FXwZSHXW0w?Q:sO + esxi1_hostname=esxi1.test + esxi1_username=zuul + esxi1_password=f6QYNi65k05kv8m56 + + +To run the tests, use the following command. You may want to adjust the Python version. + +.. code-block:: shell + + ansible-test network-integration --diff --no-temp-workdir --python 3.8 --inventory /tmp/inventory-vmware_rest zuul/ +