Integrate inventory template and various tweaks

Author: cmsirbu

docs/extra.css

@@ -0,0 +1,8 @@
+/*
+* The default max-width is 61rem which does not provide nearly enough space to present code examples or larger tables
+*/
+.md-grid {
+    margin-left: auto;
+    margin-right: auto;
+    max-width: 95%;
+}

docs/requirements.yaml

@@ -1,3 +1,4 @@
 ---
 collections:
   - name: "ansible.posix"
+  - name: "networktocode.nautobot"

mkdocs.yml

@@ -37,12 +37,21 @@ theme:
         icon: "material/weather-night"
         name: "Switch to light mode"
 
+extra_css:
+  - "extra.css"
+
 plugins:
   - "search"
   - "ansible-collection":
       "collections":
         - "ansible.builtin"
         - "ansible.posix"
+        - "networktocode.nautobot"
+
+        # - name: "ansible.builtin"
+        #   plugin_types:
+        #     - inventory
+        #     - module
 
 markdown_extensions:
   - "admonition"

mkdocs_ansible_collection/plugin.py

@@ -25,7 +25,7 @@ class AnsibleDocsPlugin(mkdocs.plugins.BasePlugin[AnsibleDocsPluginConfig]):
     """MkDocs Plugin Class."""
 
     # TODO: Remove once all plugin types have a corresponding jinja template
-    PLUGIN_MAP = {"filter": "filter"}
+    PLUGIN_MAP = {"filter": "filter", "inventory": "inventory"}
 
     def __init__(self, *args, **kwargs):
         """Instantiation."""
@@ -39,6 +39,7 @@ def __init__(self, *args, **kwargs):
             loader=FileSystemLoader(package_files("mkdocs_ansible_collection") / "templates"),
             autoescape=select_autoescape(default=True),
             trim_blocks=True,
+            lstrip_blocks=True,
         )
 
     def on_pre_build(self, config):
@@ -75,6 +76,8 @@ def on_files(self, files, config):
             collection_metadata = AnsibleDocsPlugin._get_ansible_doc_metadata(fqcn)
 
             # Generate the index for the collection sub-path
+            # TODO: extract requirements from all plugins and list on this page
+            # TODO: extract collection version
             files.append(
                 self._generate_page(
                     path=f"{fqcn}/index.md",
@@ -103,17 +106,25 @@ def on_files(self, files, config):
                     )
                 )
 
-                for plugin in plugins:
-                    plugin_name = plugin.removeprefix(fqcn + ".")
+                for plugin_fqname, plugin_data in plugins.items():
+                    if plugin_data.get("error") is not None:
+                        log.warning(
+                            f"Error returned for {plugin_fqname} by ansible-doc: {plugin_data['error']}"
+                        )
+                        continue
+                    log.debug(f"Generating page for {plugin_fqname}")
+                    plugin_name = plugin_fqname.removeprefix(fqcn + ".")
                     files.append(
                         self._generate_page(
                             path=f"{fqcn}/{plugin_type}/{plugin_name}.md",
                             site_dir=config.site_dir,
                             # TODO: replace line once the mapping is not needed
                             # template=f"{plugin_type}.md.jinja",
                             template=f"{AnsibleDocsPlugin.PLUGIN_MAP.get(plugin_type, 'default')}.md.jinja",  # noqa
-                            plugin=plugin,
-                            plugin_data=plugins[plugin],
+                            fqcn=fqcn,
+                            plugin=plugin_fqname,
+                            plugin_name=plugin_name,
+                            plugin_data=plugin_data,
                         )
                     )
 

mkdocs_ansible_collection/templates/_templates/inventory.md.j2

@@ -1,5 +1,30 @@
 # Collection - {{ fqcn }}
 
+## Useful Links
+
+- Ansible Galaxy: [{{ fqcn }}](https://galaxy.ansible.com/{{ fqcn | replace(".", "/") }})
+
+{# TODO: Find a way to extract useful URLs for the collection, like source repo, issues tracker etc. #}
+
+!!! note "Usage Note"
+     To install the collection, run:
+
+    ```
+    ansible-galaxy collection install {{ fqcn }}
+    ```
+
+    For more information about available versions, visit the [Ansible Galaxy](https://galaxy.ansible.com/{{ fqcn | replace(".", "/") }}) page.
+
+    {# {% if requirements is defined and requirements is not none %}
+    The following Python packages are needed on the host that executes this module:
+
+    {% for req in requirements %}
+    - [{{ req }}](https://pypi.org/project/{{ req }}/)
+    {% endfor %}
+    {% endif %} #}
+
+## Plugins
+
 This collection contains the following plugin types:
 
 | Plugin Type | Count |
@@ -9,3 +34,4 @@ This collection contains the following plugin types:
 | [{{ plugin_type }}](./{{ plugin_type }}/index.md) | {{ plugin_types[plugin_type] | length }}
 {% endif %}
 {% endfor %}
+

mkdocs_ansible_collection/templates/collection_index.md.jinja

@@ -0,0 +1,77 @@
+{% set pd = plugin_data['doc'] %}
+# {{ plugin_name }}
+
+!!! note "Collection Note"
+    This module is part of the [{{ fqcn }} collection](https://galaxy.ansible.com/{{ fqcn | replace(".", "/") }}). To install the collection, use:
+
+    ```
+    ansible-galaxy collection install {{ fqcn }}
+    ```
+    {% if pd['requirements'] is defined and pd['requirements'] is not none %}
+    You need further requirements to be able to use this module, see the [Requirements](#requirements) section for details.
+    {% endif %}
+
+## Synopsis
+
+{% for desc_item in pd['description'] %}
+- {{ desc_item}}
+{% endfor %}
+
+{% if pd['requirements'] is defined and pd['requirements'] is not none %}
+## Requirements
+
+The following Python packages are needed on the host that executes this module:
+
+{% for req in pd['requirements'] %}
+- [{{ req }}](https://pypi.org/project/{{ req }}/)
+{% endfor %}
+{% endif %}
+
+{% if pd['options'] is defined and pd['options'] is not none %}
+## Parameters
+
+| Parameter | Data Type | Environment Variable | Version Added | Comments |
+| --------- | --------- | -------------------- | ------------- | -------- |
+{% for param_name, param_values in pd['options'].items() %}
+{% if param_values['description'] is string %}
+| {{ param_name }} | {{ param_values['type'] }} | {% for env_var in param_values['env'] %} {{ env_var['name'] }} {% endfor %} | {{ param_values['version_added']  | default('') }} | {{ param_values['description'] }} |
+{% else %}
+| {{ param_name }} | {{ param_values['type'] }} | {% for env_var in param_values['env'] %} {{ env_var['name'] }} {% endfor %} | {{ param_values['version_added']  | default('') }} | {{ param_values['description'] | join(' ') }} |
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if pd['notes'] is defined and pd['notes'] is not none %}
+## Notes
+
+!!! note "Note"
+{% for note in pd['notes'] %}
+    - {{ note }}
+{% endfor %}
+{% endif %}
+
+## Examples
+
+```yaml
+{{ plugin_data['examples'] }}
+```
+
+{% if plugin_data['return'] is not none %}
+## Return Values
+
+| Key | Data Type | Description | Returned |
+| --- | --------- | ----------- | -------- |
+{% for key, values in plugin_data['return'].items() %}
+{% if values['description'] is string %}
+| {{ key }} | {{ values['type'] }} | {{ values['description'] }} | {{ values['returned'] }} |
+{% else %}
+| {{ key }} | {{ values['type'] }} | {{ values['description'] | join(" ") }} | {{ values['returned'] }} |
+{% endif %}
+{% endfor %}
+{% endif %}
+
+## Authors
+
+{% for author in pd['author'] %}
+- {{ author }}
+{% endfor %}