Read The Docs via Sphinx (#297)

Author: FragmentedPacket

.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 tests/output/*
 venv/
 .vscode/
+docs/_build/*
 
 # https://github.com/ansible/ansible/issues/68499
 # ansible_collections/

.readthedocs.yml

@@ -0,0 +1,8 @@
+version: 2
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  version: 3.6
+  install:
+    - requirements: docs/requirements.txt

.travis.yml

@@ -99,7 +99,7 @@ script:
   # Sanity tests
   # --requirements - install pip packages as necessary
   # Skip pep8 as we use black instead
-  - ansible-test sanity -v --requirements --python $PYTHON_VER --skip-test pep8
+  - ansible-test sanity -v --requirements --python $PYTHON_VER --skip-test pep8 plugins/
 
   # Unit tests, with code coverage
   - ansible-test units -v --coverage --python $PYTHON_VER

README.md

@@ -16,205 +16,7 @@ To keep the code simple, we only officially support the two latest releases of N
 - Ansible 2.9+
 - NetBox write-enabled token when using modules or read-only token for `nb_lookup/nb_inventory`
 
-## Existing Modules
-
-- netbox_aggregate
-- netbox_cable
-- netbox_circuit
-- netbox_circuit_termination
-- netbox_circuit_type
-- netbox_cluster
-- netbox_cluster_group
-- netbox_cluster_type
-- netbox_console_port
-- netbox_console_port_template
-- netbox_console_server_port
-- netbox_console_server_port_template
-- netbox_device_bay
-- netbox_device_bay_template
-- netbox_device_interface
-- netbox_device_interface_template
-- netbox_device_role
-- netbox_device_type
-- netbox_device
-- netbox_front_port
-- netbox_front_port_template
-- netbox_inventory_item
-- netbox_ip_address
-- netbox_ipam_role
-- netbox_manufacturer
-- netbox_platform
-- netbox_power_feed
-- netbox_power_outlet
-- netbox_power_outlet_template
-- netbox_power_panel
-- netbox_power_port
-- netbox_power_port_template
-- netbox_prefix
-- netbox_provider
-- netbox_rack_group
-- netbox_rack_role
-- netbox_rack
-- netbox_rear_port
-- netbox_rear_port_template
-- netbox_region
-- netbox_rir
-- netbox_site
-- netbox_service
-- netbox_tenant_group
-- netbox_tenant
-- netbox_virtual_chassis
-- netbox_virtual_machine
-- netbox_vm_interface
-- netbox_vlan_group
-- netbox_vlan
-- netbox_vrf
-
-## NetBox Plugins
-
-- netbox lookup plugin
-- netbox inventory plugin (0.1.5)
-
-## How to Use
-
-- Install via Galaxy
-  - `ansible-galaxy collection install netbox.netbox`
-- Install via source
-  - `git clone git@github.com:netbox-community/ansible_modules.git`
-  - `cd ansible_modules`
-  - `ansible-galaxy collection build .`
-  - `ansible-galaxy collection install netbox-netbox-X.X.X.tar.gz`
-    - Can add `-p` to provide a different path other than the default path, but it must be within your `ansible.cfg` or provided via an environment variable.
-
-### Example inventory
-
-```yaml
-plugin: netbox.netbox.nb_inventory
-api_endpoint: http://netbox-demo.org:32768
-token: 0123456789abcdef0123456789abcdef01234567
-config_context: True
-interfaces: True
-group_by:
-  - device_roles
-
-compose:
-  ansible_network_os: platform.slug
-```
-
-More configuration options and examples can be found [here](plugins/inventory/nb_inventory.py)
-
-### Example playbooks
-
-Using the **collections** at the play level
-
-```yaml
-- name: "Test NetBox modules"
-  connection: local
-  hosts: localhost
-  gather_facts: False
-  collections:
-    - netbox.netbox
-
-  tasks:
-    - name: Create device within NetBox with only required information
-      netbox_device:
-        netbox_url: http://netbox-demo.org:32768
-        netbox_token: 0123456789abcdef0123456789abcdef01234567
-        data:
-          name: Test66
-          device_type: Cisco Test
-          device_role: Core Switch
-          site: Test Site
-          status: Staged
-        state: present
-```
-
-Using the **collections** at the task level
-
-```yaml
-- name: "Test NetBox modules"
-  connection: local
-  hosts: localhost
-  gather_facts: False
-
-  tasks:
-    - name: Create device within NetBox with only required information
-      netbox.netbox.netbox_device:
-        netbox_url: http://netbox-demo.org:32768
-        netbox_token: 0123456789abcdef0123456789abcdef01234567
-        data:
-          name: Test66
-          device_type: Cisco Test
-          device_role: Core Switch
-          site: Test Site
-          status: Staged
-        state: present
-```
-
-Using the **collections** in a role's task files
-
-```yaml
----
-- name: Create device within NetBox with only required information
-  netbox.netbox.netbox_device:
-    netbox_url: http://netbox-demo.org:32768
-    netbox_token: 0123456789abcdef0123456789abcdef01234567
-    data:
-      name: Test66
-      device_type: Cisco Test
-      device_role: Core Switch
-      site: Test Site
-      status: Staged
-    state: present
-
-OR
-
----
-- name: Create device within NetBox with only required information
-  collections:
-    - netbox.netbox
-  netbox_device:
-    netbox_url: http://netbox-demo.org:32768
-    netbox_token: 0123456789abcdef0123456789abcdef01234567
-    data:
-      name: Test66
-      device_type: Cisco Test
-      device_role: Core Switch
-      site: Test Site
-      status: Staged
-    state: present
-```
-
-Using the **collections** lookup plugin at the task level
-
-```yaml
-- name: "TEST NETBOX_LOOKUP"
-  connection: local
-  hosts: localhost
-  gather_facts: False
-  collections:
-    - netbox.netbox
-  tasks:
-    - name: "NETBOX_LOOKUP 1: Lookup returns exactly two sites"
-      assert:
-        that: "{{ query_result|count }} == 3"
-      vars:
-        query_result: "{{ query('netbox.netbox.nb_lookup', 'sites', api_endpoint='http://localhost:32768', token='0123456789abcdef0123456789abcdef01234567') }}"
-```
->Note that if you are on MacOS and are running into ```ERROR! A worker was found in a dead state``` errors, try running the playbook with a ```env no_proxy='*'``` tag in front of the playbook.  This is a known issue with MacOS as per this reference: https://github.com/ansible/ansible/issues/32554#issuecomment-642896861
-
-### Using **nb_inventory** Within AWX/Tower
-
-This will cover the basic usage of the NetBox inventory plugin within this collection.
-
-1. Define `collections/requirements.yml` within a Git project.
-    1. AWX/Tower will download the collection on each run. This can be handled differently or excluded if storing Ansible Collections on the AWX/Tower box.
-    2. Define `inventory.yml` in Git project that adheres to inventory plugin structure.
-2. Add Git project to AWX/Tower as a project.
-3. Create inventory and select `source from project`.
-    1. Select the AWX/Tower project from Step 2
-    2. Select the `inventory.yml` file in the project from Step 1.1
-    3. Click `Save` and sync source.
+We have a new docs site live that can be found [here](https://netbox-ansible-collection.readthedocs.io/en/latest/)
 
 ## How to Contribute
 

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)