From 79de49adfbf928aa26539a4150d9d2925f131304 Mon Sep 17 00:00:00 2001 From: GomathiselviS Date: Fri, 15 Sep 2023 16:45:11 -0400 Subject: [PATCH] Add documention on module generation using Content Builder tool (#424) Add documention on module generation using Content Builder tool SUMMARY Fixes #423 ISSUE TYPE Bugfix Pull Request Docs Pull Request Feature Pull Request New Module Pull Request COMPONENT NAME ADDITIONAL INFORMATION Reviewed-by: Mario Lenz Reviewed-by: Helen Bailey Reviewed-by: GomathiselviS --- README.md | 13 +---- changelogs/fragments/add_dev_doc.yaml | 3 ++ development.md | 72 +++++++++++++++++++++++++++ tox.ini | 2 +- 4 files changed, 77 insertions(+), 13 deletions(-) create mode 100644 changelogs/fragments/add_dev_doc.yaml create mode 100644 development.md diff --git a/README.md b/README.md index 6d70b933e..9e0eaf4b9 100644 --- a/README.md +++ b/README.md @@ -212,18 +212,7 @@ The [VMware REST modules guide](https://docs.ansible.com/ansible/devel/scenario_ ## Development -This collection can be generated using the [content_builder](https://github.com/ansible-community/ansible.content_builder) tool. Please refer to the [cloud_content generation section](https://github.com/ansible-community/ansible.content_builder#5-vmwarevmware_rest). - -The developer can use the [api specification](https://github.com/ansible-collections/vmware.vmware_rest/tree/main/api_specifications) files and the [modules.yaml](https://github.com/ansible-collections/vmware.vmware_rest/blob/main/modules.yaml) file hosted in this repository. The path to these files should be provided as input to the content builder tool to generate the modules. To get more details on the command and input arguments please refer to the tool's [README](https://github.com/ansible-community/ansible.content_builder#resource-module-scaffolding-generated-using-openapi-based-json). - -## Testing with `ansible-test` - -``` -virtualenv -p python3.7 .virtualenv/py37 # Or any other version greater than 3.6 -source .virtualenv/py37/bin/activate -pip install -r requirements.txt -r test-requirements.txt -ansible-test network-integration --python 3.7 --inventory /tmp/inventory-vmware_rest vcenter_vm_scenario1 -``` +This collection can be generated using the [content_builder](https://github.com/ansible-community/ansible.content_builder) tool. Please refer to the [vmware module generation](https://github.com/ansible-collections/vmware.vmware_rest/blob/main/development.md). ## Release notes diff --git a/changelogs/fragments/add_dev_doc.yaml b/changelogs/fragments/add_dev_doc.yaml new file mode 100644 index 000000000..f86472d02 --- /dev/null +++ b/changelogs/fragments/add_dev_doc.yaml @@ -0,0 +1,3 @@ +--- +trivial: +- "Add documentation to explain the steps to generate modules using content_builder tool." diff --git a/development.md b/development.md new file mode 100644 index 000000000..956ca470f --- /dev/null +++ b/development.md @@ -0,0 +1,72 @@ +# VMWare + +# Development Guide +## Installation + +Install the ansible.content_builder tool. +``` +pip install black==22.3.0 jsonschema jinja2==3.0.3 ansible-core +ansible-galaxy collection install git+https://github.com/ansible-community/ansible.content_builder.git +``` + +You can also include it in a `requirements.yml` file and install it via `ansible-galaxy collection install -r requirements.yml` using the format: + +``` +collections: +- name: ansible.content_builder +``` + +See [Ansible Using collections](https://docs.ansible.com/ansible/latest/user_guide/collections_using.html) for more details. + +## Using the Content Builder tool to generate vmware modules: + +To use the content builder tool, you need to provide a YAML file that contains all the information needed to generate a vmware module. You can find the necessary files, such as the [api specification](https://github.com/ansible-collections/vmware.vmware_rest/tree/main/config/api_specifications) and the [modules.yaml](https://github.com/ansible-collections/vmware.vmware_rest/tree/main/config/modules.yaml), in the repository. You can copy these files to your local path and customize them as per your requirements. After that, you must specify the path of these files in the input yaml file against the api_object_path and resource parameter. If you want to generate both examples and modules, set the action parameter to `generate_all`. If you only want to generate examples, use `action: generate_examples`, and for only modules, use `action: generate_modules`. For more information on the command and input arguments, please refer to the tool's [README](https://github.com/ansible-community/ansible.content_builder#resource-module-scaffolding-generated-using-openapi-based-json). To generate the vmware modules using the content_builder tool, you can use the following command: + +``` +ansible-playbook build.yaml -e manifest_file=MANIFEST.yaml +``` + +The build.yaml file should contain the following code: + +```yaml +--- +- hosts: localhost + gather_facts: yes + roles: + - ansible.content_builder.run +``` + +And the MANIFEST.yaml file should contain the following code: + +```yaml +--- +collection: + path: /collections/ansible_collections/vmware/vmware_rest + namespace: vmware + name: vmware_rest +plugins: + - type: module_openapi + name: "vmware_rest" + content: cloud + api_object_path: api_specifications/7.0.2 + resource: config + action: generate_all + unique_key: "" + rm_swagger_json: "" + module_version: "1.0.0" + author: "Ansible Cloud Team" +``` + +Once the modules are generated in the location mentioned in `collection:path`, you can follow the below steps to refresh the RETURN block in the module documentaion. + +**_Refresh the `RETURN Block` of the vmware modules using the test-suite:_** + +Set the env variables mentioned in [tox.ini](https://github.com/ansible-collections/vmware.vmware_rest/blob/main/tox.ini#L47). +``` + mkdir -p ~/.ansible/collections/ansible_collections/goneri/utils + git clone https://github.com/goneri/ansible-collection-goneri.utils.git ~/.ansible/collections/ansible_collections/goneri/utils + cd ~/.ansible/collections/ansible_collections/vmware/vmware_rest/tests/integration/targets/vcenter_vm_scenario1 + ./refresh_RETURN_block.sh + cd ~/.ansible/collections/ansible_collections/goneri/utils + ./scripts/inject_RETURN.py ~/.ansible/collections/ansible_collections/vmware/vmware_rest/manual/source/vmware_rest_scenarios/task_outputs ~/.ansible/collections/ansible_collections/vmware/vmware_rest --config-file config/inject_RETURN.yaml +``` diff --git a/tox.ini b/tox.ini index 5282ce308..9ec573eea 100644 --- a/tox.ini +++ b/tox.ini @@ -10,7 +10,7 @@ install_command = pip install {opts} {packages} [testenv:black] deps = - black==19.10b0 + black click==8.0.2 commands = black {toxinidir}/plugins {toxinidir}/tests