Merge pull request #86 from equinix-labs/docs_rework

Improvements in docs generating

.github/workflows/integration-tests.yml

@@ -31,6 +31,12 @@ jobs:
       - name: install dependencies
         run: python -m pip install -r requirements-dev.txt -r requirements.txt
 
+      - name: update apt
+        run: sudo apt update
+
+      - name: install parallel
+        run: sudo apt install parallel
+
       - name: install collection
         run: make install
 

Makefile

@@ -1,7 +1,7 @@
 SHELL := /bin/bash
 COLLECTIONS_PATH ?= ~/.ansible/collections
 DOCS_PATH ?= docs
-COLLECTION_VERSION ?= 0.0.1
+COLLECTION_VERSION ?=
 
 TEST_ARGS := -v
 INTEGRATION_CONFIG := tests/integration/integration_config.yml
@@ -32,17 +32,21 @@ lint:
 	mypy plugins/inventory
 
 .PHONY: docs
-docs:
+docs: inject-module-docs
 	rm -rf $(DOCS_PATH)/modules $(DOCS_PATH)/inventory
 	mkdir -p $(DOCS_PATH)/modules $(DOCS_PATH)/inventory
 	DOCS_PATH=$(DOCS_PATH) ./scripts/specdoc_generate.sh
 	python scripts/render_readme.py ${COLLECTION_VERSION}
-	#ansible-doc-extractor --template=template/module.rst.j2 $(DOCS_PATH)/inventory plugins/inventory/*.py
+	ansible-doc-extractor --template=template/module.rst.j2 $(DOCS_PATH)/inventory plugins/inventory/metal_device.py
 
-.PHONY: injected-docs
-injected-docs:
+.PHONY: inject-module-docs
+inject-module-docs:
 	DOCS_PATH=$(DOCS_PATH) ./scripts/specdoc_inject.sh
 
+.PHONY: remove-module-docs
+remove-module-docs:
+	DOCS_PATH=$(DOCS_PATH) ./scripts/specdoc_remove.sh
+
 test: integration-test
 
 testall: create-integration-config

README.md

@@ -21,10 +21,10 @@ Modules for managing Equinix infrastructure.
 
 Name | Description |
 --- | ------------ |
-[equinix.cloud.metal_device](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_device.md)|Create, update, or delete Equinix Metal devices|
-[equinix.cloud.metal_ip_assignment](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_ip_assignment.md)|Manage Equinix Metal IP assignments|
-[equinix.cloud.metal_project](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_project.md)|Manage Projects in Equinix Metal|
-[equinix.cloud.metal_reserved_ip_block](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_reserved_ip_block.md)|Create/delete blocks of reserved IP addresses in a project.|
+[equinix.cloud.metal_device](./docs/modules/metal_device.md)|Create, update, or delete Equinix Metal devices|
+[equinix.cloud.metal_ip_assignment](./docs/modules/metal_ip_assignment.md)|Manage Equinix Metal IP assignments|
+[equinix.cloud.metal_project](./docs/modules/metal_project.md)|Manage Projects in Equinix Metal|
+[equinix.cloud.metal_reserved_ip_block](./docs/modules/metal_reserved_ip_block.md)|Create/delete blocks of reserved IP addresses in a project.|
 
 
 ### Info Modules
@@ -33,11 +33,11 @@ Modules for retrieving information about existing Equinix infrastructure.
 
 Name | Description |
 --- | ------------ |
-[equinix.cloud.metal_available_ips_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_available_ips_info.md)|Get list of avialable IP addresses from a reserved IP block|
-[equinix.cloud.metal_device_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_device_info.md)|Select list of Equinix Metal devices|
-[equinix.cloud.metal_ip_assignment_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_ip_assignment_info.md)|Gather IP address assignments for a device|
-[equinix.cloud.metal_project_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_project_info.md)|Gather information about Equinix Metal projects|
-[equinix.cloud.metal_reserved_ip_block_info](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/modules/metal_reserved_ip_block_info.md)|Gather list of reserved IP blocks|
+[equinix.cloud.metal_available_ips_info](./docs/modules/metal_available_ips_info.md)|Get list of avialable IP addresses from a reserved IP block|
+[equinix.cloud.metal_device_info](./docs/modules/metal_device_info.md)|Select list of Equinix Metal devices|
+[equinix.cloud.metal_ip_assignment_info](./docs/modules/metal_ip_assignment_info.md)|Gather IP address assignments for a device|
+[equinix.cloud.metal_project_info](./docs/modules/metal_project_info.md)|Gather information about Equinix Metal projects|
+[equinix.cloud.metal_reserved_ip_block_info](./docs/modules/metal_reserved_ip_block_info.md)|Gather list of reserved IP blocks|
 
 
 ### Inventory Plugins
@@ -46,7 +46,7 @@ Dynamically add Equinix infrastructure to an Ansible inventory.
 
 Name |
 --- |
-[equinix.cloud.metal_device](https://github.com/equinix-labs/ansible-collection-equinix/blob/0.0.1/docs/inventory/metal_device.md)|
+[equinix.cloud.metal_device](./docs/inventory/metal_device.rst)|
 
 
 <!--end collection content-->
@@ -63,17 +63,18 @@ The Python module dependencies are not installed by `ansible-galaxy`.  They can
 be manually installed using pip:
 
 ```shell
-pip install -r https://raw.githubusercontent.com/equinix-labs/ansible-collection-equinix/0.0.1/requirements.txt
+pip install -r https://raw.githubusercontent.com/equinix-labs/ansible-collection-equinix/main/requirements.txt
 ```
 
 ## Usage
 Once the Equinix Ansible collection is installed, it can be referenced by its [Fully Qualified Collection Namespace (FQCN)](https://github.com/ansible-collections/overview#terminology): `equinix.cloud.module_name`.
 
-In order to use this collection, you should have account in the relevant Equinix service. For example you should have an account Equinix Metal to use the `metal_*` plugins.
+In order to use this collection, you should have account in the relevant Equinix service. For example you should have an account in Equinix Metal to use the `metal_*` modules.
 
-You can authenticate either by exporting auth tokens as environment variables, or by supplying `*_api_token` attributes to modules. For example, to use `metal_device`, you can export `METAL_AUTH_TOKEN` (or `METAL_API_TOKEN`), or you can supply `metal_auth_token` attribute.
+You can authenticate either by exporting auth token in an environment variable, or by supplying `*_api_token` attributes to modules. For example, to use `metal_device`, you can export `METAL_AUTH_TOKEN` (or `METAL_API_TOKEN`), or you can supply the `metal_api_token` attribute.
+
+### Example Playbook
 
-#### Example Playbook
 ```yaml
 ---
 - name: create Equinix Metal device
@@ -116,23 +117,21 @@ To install the collection from local directory, do `make install` in the root of
 
 ## Releasing
 
-When releasing, make sure that the desired version number is in `COLLECTION_VERSION` variable in Makefile.
-
-Then go to [https://github.com/equinix-labs/ansible-collection-equinix/releases/new](https://github.com/ansible-collection-equinix/metal-python/releases/new) and create a new release from `main`. Don't choose an existing tag. Put `v{COLLECTION_VERSION}` to the field for "Release title". For example if COLLECTION_VERSION is "0.1.2", use "v0.1.2".
+Go to [https://github.com/equinix-labs/ansible-collection-equinix/releases/new](https://github.com/ansible-collection-equinix/metal-python/releases/new) and create a new release from `main`. Don't choose an existing tag. Put version to the field for "Release title", for example `v0.1.2`. Don't add collection number to the Makefile.
 
 Add release notes in format of [Terraform Provider Equinix](https://github.com/equinix/terraform-provider-equinix/releases), with at least one of the sections (NOTES, FEATURES, BUG FIXES, ENHANCEMENTS).
 
 Click "Publish release", and the manual part should be over.
 
-The release will create a tag, and we have a Github action in place that should create an Ansible Galaxy release for version from COLLECTION_VERSION.
+The release will create a tag, and we have a Github action in place that should create an Ansible Galaxy release. The script that creates tarball for Galay removes the first "v", so releasing `v0.1.2` should upload collection equinix.cloud version 0.1.2.
 
 Verify that the [releasing Github action](https://github.com/equinix-labs/ansible-collection-equinix/actions) succeeded.
 
-Verify that new version of [equinix.cloud](https://galaxy.ansible.com/equinix/cloud) is avaiable in Ansible Galaxy.
+Verify that new version of [equinix.cloud](https://galaxy.ansible.com/equinix/cloud) is available in Ansible Galaxy.
 
 
 ## Licensing
 
 GNU General Public License v3.0.
 
-See [COPYING](COPYING) to see the full text.
+See [COPYING](COPYING) to see the full text.

docs/inventory/metal_device.rst

@@ -0,0 +1,150 @@
+.. _metal_device_module:
+
+
+metal_device -- Equinix Metal Device inventory source
+=====================================================
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+
+Reads device inventories from Equinix Metal. Uses YAML configuration file that ends with equinix_metal.(yml|yaml). ansible_host is set to first public IP address of the device.
+
+
+
+Requirements
+------------
+The below requirements are needed on the host that executes this module.
+
+- python >= 3
+- metal_python >= 0.0.1
+
+
+
+Parameters
+----------
+
+  **plugin (Required, type=str):**
+    \• Token that ensures this is a source file for the plugin.
+
+    \• Options: `equinix_metal`, `equinix.cloud.metal_device`
+
+
+  **metal_api_token (Required, type=str):**
+    \• Equinix Metal API token. Can also be specified via METAL_AUTH_TOKEN environment variable.
+
+
+
+  **project_ids (type=list):**
+    \• List of Equinix Metal project IDs to query for devices.
+
+
+  **strict (type=bool):**
+    \• If ``yes`` make invalid entries a fatal error, otherwise skip and continue.
+
+    \• Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.
+
+
+  **compose (type=dict):**
+    \• Create vars from jinja2 expressions.
+
+
+  **groups (type=dict):**
+    \• Add hosts to group based on Jinja2 conditionals.
+
+
+  **keyed_groups (type=list):**
+    \• Add hosts to group based on the values of a variable.
+
+
+      **parent_group (type=str):**
+        \• parent group for keyed group
+
+
+      **prefix (type=str):**
+        \• A keyed group name will start with this prefix
+
+
+      **separator (type=str, default=_):**
+        \• separator used to build the keyed group name
+
+
+      **key (type=str):**
+        \• The key from input dictionary used to generate groups
+
+
+      **default_value (type=str):**
+        \• The default value when the host variable's value is an empty string.
+
+        \• This option is mutually exclusive with ``trailing_separator``.
+
+
+      **trailing_separator (type=bool, default=True):**
+        \• Set this option to *False* to omit the ``separator`` after the host variable when the value is an empty string.
+
+        \• This option is mutually exclusive with ``default_value``.
+
+
+
+  **use_extra_vars (type=bool):**
+    \• Merge extra vars into the available variables for composition (highest precedence).
+
+
+  **leading_separator (type=boolean, default=True):**
+    \• Use in conjunction with keyed_groups.
+
+    \• By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.
+
+    \• This is because the default prefix is "" and the default separator is "_".
+
+    \• Set this option to False to omit the leading underscore (or other separator) if no prefix is given.
+
+    \• If the group name is derived from a mapping the separator is still used to concatenate the items.
+
+    \• To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.
+
+
+
+
+
+
+
+Examples
+--------
+
+.. code-block:: yaml+jinja
+
+
+    plugin: equinix.cloud.metal_device
+    strict: false
+    keyed_groups:
+      - prefix: tag
+        key: tags
+      - prefix: equinix_metal_plan
+        key: plan
+      - key: metro
+        prefix: equinix_metal_metro
+      - key: state
+        prefix: equinix_metal_state
+
+
+
+
+
+
+Status
+------
+
+
+
+
+
+Authors
+~~~~~~~
+
+- Equinix DevRel Team (@equinix) <[email protected]>
+