-
Notifications
You must be signed in to change notification settings - Fork 64
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move Dev Guide to collection Depends-On: #331 SUMMARY Collection-specific docs must move to their collections. ISSUE TYPE Docs Pull Request COMPONENT NAME docsite ADDITIONAL INFORMATION see here cc @samccann Reviewed-by: Abhijeet Kasurde <None> Reviewed-by: Sandra McCann <[email protected]>
- Loading branch information
Showing
2 changed files
with
114 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,3 +3,6 @@ sections: | |
- title: Scenario Guide | ||
toctree: | ||
- guide_vmware_rest | ||
- title: Developer Guide | ||
toctree: | ||
- dev_guide |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,111 @@ | ||
.. _ansible_collections.vmware.vmware_rest.docsite.vmware_rest_devguide: | ||
|
||
********************************************* | ||
Guidelines for VMware REST module development | ||
********************************************* | ||
|
||
The Ansible VMware REST collection (on `Galaxy <https://galaxy.ansible.com/vmware/vmware_rest>`_, source code `repository <https://github.com/ansible-collections/vmware.vmware_rest>`_) 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 <https://github.com/ansible-collections/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 criteria. | ||
|
||
Requirements | ||
============ | ||
|
||
You will need: | ||
|
||
- Python 3.6 or greater | ||
- the `tox <https://tox.readthedocs.io/en/latest/install.html>` command | ||
|
||
|
||
vmware_rest_code_generator | ||
========================== | ||
|
||
Your contribution should follow the coding style of `Black <https://github.com/psf/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 `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 <https://github.com/psf/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 `/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[email protected] | ||
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/ | ||