Merge pull request #21 from LBGarber/docs_generation

Added module docs generation

Makefile

@@ -12,6 +12,11 @@ build:
 install: clean build
 	ansible-galaxy collection install *.tar.gz --force -p $(COLLECTIONS_PATH)
 
+gendocs:
+	mkdir -p docs
+	rm -f docs/*
+	ansible-doc-extractor --template=template/module.rst.j2 docs plugins/modules/*.py
+
 integration-test: $(INTEGRATION_CONFIG)
 	ansible-test integration $(TEST_ARGS)
 

README.md

@@ -11,6 +11,21 @@ A collection may contain metadata that identifies these versions.
 PEP440 is the schema used to describe the versions of Ansible.
 <!--end requires_ansible-->
 
+<!--start collection content-->
+### Modules
+Name | Description
+--- | ---
+[linode.cloud.instance](https://github.com/linode/ansible_linode/blob/master/docs/instance.rst)|Create and destroy Linodes.
+[linode.cloud.instance_info](https://github.com/linode/ansible_linode/blob/master/docs/instance_info.rst)|Gather info about an existing Linode instance.
+[linode.cloud.nodebalancer](https://github.com/linode/ansible_linode/blob/master/docs/nodebalancer.rst)|Create, destroy, and configure NodeBalancers.
+[linode.cloud.nodebalancer_info](https://github.com/linode/ansible_linode/blob/master/docs/nodebalancer_info.rst)|Gather info about an existing NodeBalancer.
+[linode.cloud.object_cluster_info](https://github.com/linode/ansible_linode/blob/master/docs/object_cluster_info.rst)|Gather info about Object Storage clusters.
+[linode.cloud.object_keys](https://github.com/linode/ansible_linode/blob/master/docs/object_keys.rst)|Create and destroy Object Storage keys.
+[linode.cloud.volume](https://github.com/linode/ansible_linode/blob/master/docs/volume.rst)|Create, destroy, and attach Linode volumes.
+[linode.cloud.volume_info](https://github.com/linode/ansible_linode/blob/master/docs/volume_info.rst)|Gather info about an existing Linode volume.
+
+<!--end collection content-->
+
 ## Installation
 
 You can install the Linode collection with the Ansible Galaxy CLI:

docs/instance.rst

@@ -0,0 +1,200 @@
+.. _instance_module:
+
+
+instance
+========
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+
+Manage Linode instances.
+
+
+
+Requirements
+------------
+The below requirements are needed on the host that executes this module.
+
+- python >= 2.7
+- linode_api4 >= 3.0
+
+
+
+Parameters
+----------
+
+  label (True, string, None)
+    The unique label to give this instance.
+
+
+  type (optional, any, None)
+    The type or plan of this instance.
+
+    See https://api.linode.com/v4/linode/types
+
+
+  region (True, str, None)
+    The location to deploy the instance in.
+
+    See https://api.linode.com/v4/regions
+
+
+  image (True, str, None)
+    The image ID to deploy the instance disk from.
+
+
+  group (False, str, None)
+    The group that the instance should be marked under. Please note, that group labelling is deprecated but still supported. The encouraged method for marking instances is to use tags.
+
+
+  tags (False, list, None)
+    The tags that the instance should be marked under.
+
+    See https://www.linode.com/docs/api/tags/.
+
+
+  root_pass (False, str, None)
+    The password for the root user. If not specified, one will be generated. This generated password will be available in the task success JSON.
+
+
+  private_ip (False, bool, None)
+    If true, the created Linode will have private networking enabled.
+
+
+  authorized_keys (False, list, None)
+    A list of SSH public key parts to deploy for the root user.
+
+
+  stackscript_id (False, int, None)
+    The ID of the StackScript to use when creating the instance. See https://www.linode.com/docs/api/stackscripts/.
+
+
+  stackscript_data (False, dict, None)
+    An object containing arguments to any User Defined Fields present in the StackScript used when creating the instance. Only valid when a stackscript_id is provided. See https://www.linode.com/docs/api/stackscripts/.
+
+
+  state (optional, str, None)
+    The desired instance state.
+
+
+
+
+
+
+
+
+
+Examples
+--------
+
+.. code-block:: yaml+jinja
+
+
+    - name: Create a new Linode instance.
+      linode.cloud.instance:
+        label: my-linode
+        type: g6-nanode-1
+        region: us-east
+        image: linode/ubuntu20.04
+        root_pass: verysecurepassword!!!
+        private_ip: false
+        authorized_keys:
+          - "ssh-rsa ..."
+        stackscript_id: 1337
+        stackscript_data:
+          variable: value
+        group: app
+        tags:
+          - env=prod
+        state: present
+
+    - name: Delete that new Linode instance.
+      linode.cloud.instance:
+        label: my-linode
+        state: absent
+
+
+
+
+Return Values
+-------------
+
+**instance (always, dict):**
+
+The instance description in JSON serialized form.
+
+`Linode Response Object Documentation <https://www.linode.com/docs/api/linode-instances/#linode-view__responses>`_
+
+Sample Response:
+
+.. code-block:: JSON
+
+    {
+     "alerts": {
+      "cpu": 90,
+      "io": 10000,
+      "network_in": 10,
+      "network_out": 10,
+      "transfer_quota": 80
+     },
+     "backups": {
+      "enabled": false,
+      "schedule": {
+       "day": null,
+       "window": null
+      }
+     },
+     "created": "2018-09-26T08:12:33",
+     "group": "app",
+     "hypervisor": "kvm",
+     "id": "xxxxxx",
+     "image": "linode/ubuntu20.04",
+     "ipv4": [
+      "xxx.xxx.xxx.xxx"
+     ],
+     "ipv6": "xxxx:xxxx::xxxx:xxxx:xxxx:xxxx/64",
+     "label": "my-linode",
+     "region": "us-east",
+     "root_pass": "foobar",
+     "specs": {
+      "disk": 25600,
+      "memory": 1024,
+      "transfer": 1000,
+      "vcpus": 1
+     },
+     "status": "running",
+     "tags": [
+      "env=prod"
+     ],
+     "type": "g6-nanode-1",
+     "updated": "2018-09-26T10:10:14",
+     "watchdog_enabled": true
+    }
+
+
+
+
+
+Status
+------
+
+
+
+
+- This module is maintained by Linode.
+
+
+
+Authors
+~~~~~~~
+
+- Luke Murphy (@decentral1se)
+- Charles Kenney (@charliekenney23)
+- Phillip Campbell (@phillc)
+- Lena Garber (@lbgarber)
+

docs/instance_info.rst

@@ -0,0 +1,138 @@
+.. _instance_info_module:
+
+
+instance_info
+=============
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+
+Get info about a Linode instance.
+
+
+
+Requirements
+------------
+The below requirements are needed on the host that executes this module.
+
+- python >= 2.7
+- linode_api4 >= 3.0
+
+
+
+Parameters
+----------
+
+  label (optional, string, None)
+    The instance’s label.
+
+
+  id (optional, int, None)
+    The unique id of the instance.
+
+
+
+
+
+
+
+
+
+Examples
+--------
+
+.. code-block:: yaml+jinja
+
+
+    - name: Get info about an instance by label
+      linode.cloud.instance_info:
+        label: 'my-instance'
+
+    - name: Get info about an instance by id
+      linode.cloud.instance_info:
+        id: 12345
+
+
+
+
+Return Values
+-------------
+
+**instance (always, dict):**
+
+The instance description in JSON serialized form.
+
+`Linode Response Object Documentation <https://www.linode.com/docs/api/linode-instances/#linode-view__responses>`_
+
+Sample Response:
+
+.. code-block:: JSON
+
+    {
+     "alerts": {
+      "cpu": 90,
+      "io": 10000,
+      "network_in": 10,
+      "network_out": 10,
+      "transfer_quota": 80
+     },
+     "backups": {
+      "enabled": false,
+      "schedule": {
+       "day": null,
+       "window": null
+      }
+     },
+     "created": "xxxx-xx-xxTxx:xx:xx",
+     "group": "app",
+     "hypervisor": "kvm",
+     "id": "xxxxxx",
+     "image": "linode/ubuntu20.04",
+     "ipv4": [
+      "xxx.xxx.xxx.xxx"
+     ],
+     "ipv6": "xxxx:xxxx::xxxx:xxxx:xxxx:xxxx/64",
+     "label": "my-linode",
+     "region": "us-east",
+     "specs": {
+      "disk": 25600,
+      "memory": 1024,
+      "transfer": 1000,
+      "vcpus": 1
+     },
+     "status": "running",
+     "tags": [
+      "env=prod"
+     ],
+     "type": "g6-nanode-1",
+     "updated": "xxxx-xx-xxTxx:xx:xx",
+     "watchdog_enabled": true
+    }
+
+
+
+
+
+Status
+------
+
+
+
+
+- This module is maintained by Linode.
+
+
+
+Authors
+~~~~~~~
+
+- Luke Murphy (@decentral1se)
+- Charles Kenney (@charliekenney23)
+- Phillip Campbell (@phillc)
+- Lena Garber (@lbgarber)
+