Documentation: Store doc builds in repo (#427)

Author: FragmentedPacket

.readthedocs.yml

@@ -1,6 +1,6 @@
 version: 2
-sphinx:
-  configuration: docs/conf.py
+#sphinx:
+#  configuration: docs/conf.py
 
 python:
   version: 3.6

docs/changelog/index.rst

@@ -1,3 +1,6 @@
+=====================
+CHANGELOG
+=====================
 
 .. toctree::
    :maxdepth: 4

docs/conf.py

@@ -15,7 +15,7 @@
 import re
 import stat
 from pathlib import Path
-from antsibull.cli.antsibull_docs import run
+from antsibull.cli import antsibull_docs
 
 sys.path.insert(0, os.path.abspath("../"))
 
@@ -27,7 +27,7 @@
 author = "Mikhail Yohman <@FragmentedPacket>"
 
 # The full version, including alpha/beta/rc tags
-release = "1.1.0"
+release = "2.0.0"
 
 
 # -- General configuration ---------------------------------------------------
@@ -84,18 +84,25 @@ def create_antsibull_docs(files, plugin_type=None):
     """
     for f in files:
         file_name = re.search(r"(?:.+\/)(\S+)\.py", str(f)).group(1)
-        if file_name == "netbox_interface":
+        if file_name in ["netbox_interface"]:
             continue
 
+        print(file_name)
         if plugin_type is not None:
-            args_string = f"junk plugin --dest-dir plugins/{plugin_type}/{file_name}/ --plugin-type {plugin_type} netbox.netbox.{file_name}"
+            file_path = Path(f"plugins/{plugin_type}/{file_name}/")
         else:
-            args_string = f"junk plugin --dest-dir plugins/modules/{file_name}/ --plugin-type module netbox.netbox.{file_name}"
+            file_path = Path(f"plugins/modules/{file_name}/")
+
+        file_path.mkdir(mode=744, exist_ok=True)
+
+        if plugin_type is not None:
+            args_string = f"junk plugin --dest-dir {file_path} --plugin-type {plugin_type} netbox.netbox.{file_name}"
+        else:
+            args_string = f"junk plugin --dest-dir {file_path} --plugin-type module netbox.netbox.{file_name}"
         args = args_string.split(" ")
         try:
-            run(args)
-        except:
-            print(args)
+            antsibull_docs.run(args)
+        except Exception as e:
             sys.exit(1)
 
 
@@ -113,30 +120,32 @@ def build_ansible_docs(app):
     """
     This will perform all necessary actions to use antsibull-docs to generate collection docs
     """
-    if os.environ.get("READTHEDOCS") != "True":
-        inventory_path = Path("../plugins/inventory/")
-        lookup_path = Path("../plugins/lookup/")
-        modules_path = Path("../plugins/modules/")
+    inventory_path = Path("../plugins/inventory/")
+    lookup_path = Path("../plugins/lookup/")
+    modules_path = Path("../plugins/modules/")
 
-        # Set permissions on folders within docs/plugins to remove w from g+o
-        doc_modules = Path("plugins/modules/")
-        doc_lookup = Path("plugins/lookup/")
-        doc_inventory = Path("plugins/inventory/")
-        remove_write_permissions(doc_modules)
-        remove_write_permissions(doc_lookup)
-        remove_write_permissions(doc_inventory)
+    # Set permissions on folders within docs/plugins to remove w from g+o
+    doc_modules = Path("plugins/modules/")
+    doc_lookup = Path("plugins/lookup/")
+    doc_inventory = Path("plugins/inventory/")
+    remove_write_permissions(doc_modules)
+    remove_write_permissions(doc_lookup)
+    remove_write_permissions(doc_inventory)
 
-        inventory = inventory_path.glob("[!_]*.py")
-        lookup = lookup_path.glob("[!_]*.py")
-        modules = modules_path.glob("[!_]*.py")
+    inventory = inventory_path.glob("[!_]*.py")
+    lookup = lookup_path.glob("[!_]*.py")
+    modules = modules_path.glob("[!_]*.py")
 
-        create_antsibull_docs(inventory, "inventory")
-        create_antsibull_docs(lookup, "lookup")
-        create_antsibull_docs(modules)
+    create_antsibull_docs(inventory, "inventory")
+    create_antsibull_docs(lookup, "lookup")
+    create_antsibull_docs(modules)
 
 
-def setup(app):
-    app.connect("builder-inited", build_ansible_docs)
+###########################################
+# NOT IN USE AND SHOULD BE MANUALLY BUILT
+################
+# def setup(app):
+#    app.connect("builder-inited", build_ansible_docs)
 
 
-build_ansible_docs(None)
+# build_ansible_docs(None)

docs/getting_started/contributing/modules/new_module.rst

@@ -424,9 +424,38 @@ Next we'll create a new file named ``tests/integration/targets/latest/netbox_rou
 I won't be posting the actual implementation of this as it is a few hundred lines long, but you can view it by browsing to the specific file. To run the integration tests, it is best to push your changes up
 and let CI/CD pipeline to run, but we will be updating the development to allow local testing.
 
-After all tests pass, open a PR and wait for feedback or for the PR to be merged in.
+After all tests pass, let's generate our new documents. From the root of the collection, run the following commands.
 
-This new model within NetBox is also tied to VRFs as ``import_targets`` and ``export_targets``. Here is a screenshot of the new options we will need to add to the :ref:`netbox_vrf module<ansible_collections.netbox.netbox.netbox_vrf>`.
+.. code-block:: bash
+
+  ❯ poetry shell && poetry install
+  ❯ ./hacking/make-docs.sh
+  rm: tests/output: No such file or directory
+  rm: .pytest_cache: No such file or directory
+  Using /Users/myohman/cloned-repos/ansible_modules/ansible.cfg as config file
+  Created collection for netbox.netbox at /Users/myohman/cloned-repos/ansible_modules/netbox-netbox-2.0.0.tar.gz
+  Starting galaxy collection install process
+  [WARNING]: The specified collections path '/Users/myohman/cloned-repos/ansible_modules' is not part of the configured Ansible collections paths
+  '/Users/myohman/.ansible/collections:/usr/share/ansible/collections'. The installed collection won't be picked up in an Ansible run.
+  Process install dependency map
+  Starting collection install process
+  Installing 'netbox.netbox:2.0.0' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/netbox/netbox'
+  netbox.netbox (2.0.0) was installed successfully
+  Installing 'ansible.netcommon:1.4.1' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/ansible/netcommon'
+  Downloading https://galaxy.ansible.com/download/ansible-netcommon-1.4.1.tar.gz to /Users/myohman/.ansible/tmp/ansible-local-4390k59zwzli/tmp5871aum5
+  ansible.netcommon (1.4.1) was installed successfully
+  Installing 'community.general:1.3.4' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/community/general'
+  Downloading https://galaxy.ansible.com/download/community-general-1.3.4.tar.gz to /Users/myohman/.ansible/tmp/ansible-local-4390k59zwzli/tmp5871aum5
+  community.general (1.3.4) was installed successfully
+  Installing 'google.cloud:1.0.1' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/google/cloud'
+  Downloading https://galaxy.ansible.com/download/google-cloud-1.0.1.tar.gz to /Users/myohman/.ansible/tmp/ansible-local-4390k59zwzli/tmp5871aum5
+  google.cloud (1.0.1) was installed successfully
+  Installing 'community.kubernetes:1.1.1' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/community/kubernetes'
+  Downloading https://galaxy.ansible.com/download/community-kubernetes-1.1.1.tar.gz to /Users/myohman/.ansible/tmp/ansible-local-4390k59zwzli/tmp5871aum5
+  community.kubernetes (1.1.1) was installed successfully
+  ERROR:antsibull:error=Cannot find plugin:func=get_ansible_plugin_info:mod=antsibull.docs_parsing.ansible_internal:plugin_name=netbox.netbox.netbox_interface:plugin_type=module|Error while extracting documentation. Will not document this plugin.
+
+Let's move onto updating ``netbox_vrf`` module. This new model within NetBox is also tied to VRFs as ``import_targets`` and ``export_targets``. Here is a screenshot of the new options we will need to add to the :ref:`netbox_vrf module<ansible_collections.netbox.netbox.netbox_vrf>`.
 
 .. image:: ./media/vrf_options.png
 

docs/getting_started/contributing/modules/update_module.rst

@@ -193,4 +193,35 @@ Next we'll update ``netbox_vrf.yml`` for the **latest** integration target.
 
 We added the **import_targets** and **export_targets** when updating the VRF and then asserting that the length of both the **after** and **vrf** object are both one.
 
+Let's generate our new documents. From the root of the collection, run the following commands.
+
+.. code-block:: bash
+
+  ❯ poetry shell && poetry install
+  ❯ ./hacking/make-docs.sh
+  rm: tests/output: No such file or directory
+  rm: .pytest_cache: No such file or directory
+  Using /Users/myohman/cloned-repos/ansible_modules/ansible.cfg as config file
+  Created collection for netbox.netbox at /Users/myohman/cloned-repos/ansible_modules/netbox-netbox-2.0.0.tar.gz
+  Starting galaxy collection install process
+  [WARNING]: The specified collections path '/Users/myohman/cloned-repos/ansible_modules' is not part of the configured Ansible collections paths
+  '/Users/myohman/.ansible/collections:/usr/share/ansible/collections'. The installed collection won't be picked up in an Ansible run.
+  Process install dependency map
+  Starting collection install process
+  Installing 'netbox.netbox:2.0.0' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/netbox/netbox'
+  netbox.netbox (2.0.0) was installed successfully
+  Installing 'ansible.netcommon:1.4.1' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/ansible/netcommon'
+  Downloading https://galaxy.ansible.com/download/ansible-netcommon-1.4.1.tar.gz to /Users/myohman/.ansible/tmp/ansible-local-4390k59zwzli/tmp5871aum5
+  ansible.netcommon (1.4.1) was installed successfully
+  Installing 'community.general:1.3.4' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/community/general'
+  Downloading https://galaxy.ansible.com/download/community-general-1.3.4.tar.gz to /Users/myohman/.ansible/tmp/ansible-local-4390k59zwzli/tmp5871aum5
+  community.general (1.3.4) was installed successfully
+  Installing 'google.cloud:1.0.1' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/google/cloud'
+  Downloading https://galaxy.ansible.com/download/google-cloud-1.0.1.tar.gz to /Users/myohman/.ansible/tmp/ansible-local-4390k59zwzli/tmp5871aum5
+  google.cloud (1.0.1) was installed successfully
+  Installing 'community.kubernetes:1.1.1' to '/Users/myohman/cloned-repos/ansible_modules/ansible_collections/community/kubernetes'
+  Downloading https://galaxy.ansible.com/download/community-kubernetes-1.1.1.tar.gz to /Users/myohman/.ansible/tmp/ansible-local-4390k59zwzli/tmp5871aum5
+  community.kubernetes (1.1.1) was installed successfully
+  ERROR:antsibull:error=Cannot find plugin:func=get_ansible_plugin_info:mod=antsibull.docs_parsing.ansible_internal:plugin_name=netbox.netbox.netbox_interface:plugin_type=module|Error while extracting documentation. Will not document this plugin.
+
 We'll push these up and let the CI/CD run and then these tests should pass and then we're good to submit a PR.

docs/getting_started/how-to-use/modules.rst

@@ -79,7 +79,7 @@ The next step is to then compare the object obtained from NetBox to the data pas
 Hopefully this helps paint a picture as to why certain design decisions were made and how you can better consume this collection. Let's move onto some examples.
 
 State: Present - Create
-+++++++++++++++++
++++++++++++++++++++++++++++++
 
 When creating an object, you will need to provide the same arguments as you would if you were creating an object via the API.
 
@@ -143,7 +143,7 @@ For reference, here is the code that **slugifies** the ``name`` argument when a
 Now that we have a better understanding of why certain arguments are required or not, let's look into updating an existing object.
 
 State: Present - Update
-+++++++++++++++++
++++++++++++++++++++++++++++++
 
 Now that we have created our device (**Test Device**), let's update it by adding a serial number.
 
@@ -173,7 +173,7 @@ We're only providing the **name** which makes the device unique and then the arg
 
 
 State: Absent - Delete
-+++++++++++++++++
++++++++++++++++++++++++++++++
 
 The uniqueness of the device (**name** or user specified **query_params**) and the ``state`` set to ``absent`` are the only requirements for deleting an object.
 

docs/index.rst

@@ -17,4 +17,5 @@ Contents
    Getting Started <getting_started/index>
    Advanced Usage <advanced/index>
    Plugins <plugins/index>
+   Module Utils (Python) Docs <module_utils/index>
    Changelog <changelog/index>