Better autogenerated doc

README.md

@@ -1,3 +1,4 @@
+<!--- This is an autogenerated file, see `scripts/build_docs.py` for more info. --->
 # Vidimensional's Ansible collection
 
 ![main workflow](https://github.com/Vidimensional/ansible_collection/actions/workflows/workflow_main.yaml/badge.svg)
@@ -10,6 +11,10 @@ Collection of Ansible plugins and modules for my usage. But you can use them if
 ansible-galaxy collection install vidimensional.collection
 ```
 
-## Docs
+## Content
 
-You can check the plugins documentation [here](docs/index.md).
+### plugins
+
+#### lookup
+
+- **[github_release](docs/lookup_github_release.md)** - Lookup release information for a given GitHub repository.

README.md.j2

@@ -0,0 +1,22 @@
+{# Add autogenerated file comment #}<!--- This is an autogenerated file, see `scripts/build_docs.py` for more info. --->
+# Vidimensional's Ansible collection
+
+![main workflow](https://github.com/Vidimensional/ansible_collection/actions/workflows/workflow_main.yaml/badge.svg)
+
+Collection of Ansible plugins and modules for my usage. But you can use them if you like :)
+
+## Installation
+
+```shell
+ansible-galaxy collection install vidimensional.collection
+```
+
+## Content
+
+### plugins
+
+#### lookup
+{% for lookup in plugins_lookup %}
+- **[{{ lookup.documentation.name }}](docs/lookup_{{ lookup.documentation.name }}.md)** - {{ lookup.documentation.short_description }}
+{%- endfor %}
+

docs/lookup_github_release.md

@@ -1,3 +1,4 @@
+<!--- This is an autogenerated file, see `scripts/build_docs.py` for more info. --->
 # github_release lookup
 
 Lookup release information for a given GitHub repository.
@@ -51,14 +52,6 @@ constrain.
 ## Keyword parameters
 
 
-#### allow_prereleases
-
-- **Description:** If False it'll ignore the releases with [pre-release versions](https://semver.org/spec/v2.0.0.html#spec-item-9).
-- **Type:** boolean
-- **Required:** False
-- **Version added:** 0.0.1
-
-
 #### repo
 
 - **Description:** GitHub repository to query (`USER/REPO_NAME`).
@@ -83,6 +76,14 @@ constrain.
 - **Version added:** 0.0.1
 
 
+#### allow_prereleases
+
+- **Description:** If False it'll ignore the releases with [pre-release versions](https://semver.org/spec/v2.0.0.html#spec-item-9).
+- **Type:** boolean
+- **Required:** False
+- **Version added:** 0.0.1
+
+
 
 ## Author
 

docs/templates/lookup.md.j2

@@ -1,6 +1,7 @@
-# {{ doc.name }} lookup
+{# Add autogenerated file comment #}<!--- This is an autogenerated file, see `scripts/build_docs.py` for more info. --->
+# {{ documentation.name }} lookup
 
-{{ doc.short_description }}
+{{ documentation.short_description }}
 
 ## Table of contents
 
@@ -12,10 +13,10 @@
 
 ## Synopsis
 
-{{ doc.description }}
+{{ documentation.description }}
 
 ## Requirements
-{% for req in doc.requirements %}
+{% for req in documentation.requirements %}
 - {{ req -}}
 {% endfor %}
 
@@ -27,15 +28,15 @@
 
 ## Keyword parameters
 
-{% for key in doc.options %}
+{% for key in documentation.options %}
 #### {{ key }}
 
-- **Description:** {{ doc.options[key].description }}
-- **Type:** {{ doc.options[key].type }}
-- **Required:** {{ doc.options[key].required }}
-- **Version added:** {{ doc.options[key].version_added }}
-{% if doc.options[key].choices is defined %}- **Choices:**
-{%- for choice in doc.options[key].choices %}
+- **Description:** {{ documentation.options[key].description }}
+- **Type:** {{ documentation.options[key].type }}
+- **Required:** {{ documentation.options[key].required }}
+- **Version added:** {{ documentation.options[key].version_added }}
+{% if documentation.options[key].choices is defined %}- **Choices:**
+{%- for choice in documentation.options[key].choices %}
   - {{ choice }}
 {%- endfor %}
 {% endif %}
@@ -44,3 +45,4 @@
 ## Author
 
 - Daniel Vidal de la Rubia ([@vidimensional](https://github.com/Vidimensional))
+

galaxy.yml.j2

@@ -6,7 +6,7 @@ readme: "README.md"
 authors:
   - "Daniel Vidal de la Rubia (https://github.com/vidimensional)"
 repository: https://github.com/Vidimensional/ansible_collection
-homepage: https://github.com/Vidimensional/ansible_collection
+homepage: https://github.com/Vidimensional/ansible_collection/blob/main/README.md
 issues: https://github.com/Vidimensional/ansible_collection/issues
 documentation: https://github.com/Vidimensional/ansible_collection/blob/main/docs/index.md
 license:

requirements-dev.txt

@@ -1,2 +1,3 @@
 pytest
 j2cli
+pyyaml

scripts/build_docs.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python
+
+# Copyright © 2023 Daniel Vidal de la Rubia <https://github.com/Vidimensional>
+#
+# This work is free. You can redistribute it and/or modify it under the
+# terms of the Do What The Fuck You Want To Public License, Version 2,
+# as published by Sam Hocevar. See the LICENSE file for more details.
+
+import importlib
+import os
+import pkgutil
+import sys
+
+from types import ModuleType
+
+import jinja2
+import yaml
+
+
+def get_documentation_from_plugin_file(plugin_name: str) -> dict:
+    plugin = importlib.import_module(plugin_name)
+
+    return {
+        "documentation": yaml.safe_load(plugin.DOCUMENTATION),
+        "examples": str(plugin.EXAMPLES),
+    }
+
+
+def get_plugin_type_documentation(plugin_type: ModuleType) -> list[dict]:
+    plugins_path = plugin_type.__path__
+    sys.path += plugins_path
+
+    return [
+        get_documentation_from_plugin_file(pkg.name)
+        for pkg in pkgutil.iter_modules(plugins_path)
+    ]
+
+
+class Jinja2TemplateGenerator:
+    def __init__(self, j2_env):
+        self.j2_env = j2_env
+
+    def generate_readme(self, doc):
+        tpl = self.j2_env.get_template("README.md.j2")
+        with open("README.md", "w") as md_file:
+            md_file.write(tpl.render(doc))
+
+    def generate_plugin_documentation(self, plugin_type, plugins_info):
+        tpl = self.j2_env.get_template(f"{plugin_type}.md.j2")
+        for plugin in plugins_info:
+            plugin_name = plugin["documentation"]["name"]
+            with open(f"docs/{plugin_type}_{plugin_name}.md", "w") as md_file:
+                md_file.write(tpl.render(plugin))
+
+    def generate_plugins_lookup_documentation(self, plugins_lookup_info):
+        self.generate_plugin_documentation("lookup", plugins_lookup_info)
+
+
+if __name__ == "__main__":
+    sys.path.append(os.getcwd())
+    lookups_module = importlib.import_module("plugins.lookup")
+    doc = {"plugins_lookup": get_plugin_type_documentation(lookups_module)}
+
+    j2 = Jinja2TemplateGenerator(
+        jinja2.Environment(
+            loader=jinja2.FileSystemLoader(["docs/templates", "."]),
+            autoescape=jinja2.select_autoescape(),
+        )
+    )
+
+    j2.generate_readme(doc)
+    j2.generate_plugins_lookup_documentation(doc["plugins_lookup"])

tests/sanity/ignore-2.13.txt

@@ -1,2 +1 @@
 plugins/lookup/github_release.py validate-modules:missing-gplv3-license # 🤷 https://github.com/ansible/ansible/issues/67032#issuecomment-581439436
-"scripts/build_docs.sh shebang

tests/sanity/ignore-2.14.txt

@@ -1,2 +1 @@
 plugins/lookup/github_release.py validate-modules:missing-gplv3-license # 🤷 https://github.com/ansible/ansible/issues/67032#issuecomment-581439436
-"scripts/build_docs.sh shebang

tests/sanity/ignore-2.15.txt

@@ -1,2 +1 @@
 plugins/lookup/github_release.py validate-modules:missing-gplv3-license # 🤷 https://github.com/ansible/ansible/issues/67032#issuecomment-581439436
-scripts/build_docs.sh shebang