Merge pull request #68 from telekom-mms/feature/meta_main

feat(meta): add support for reading from meta/main

aar_doc/cli.py

@@ -158,38 +158,40 @@ def parse_meta(ctx: typer.Context) -> tuple[dict, dict]:
     """
 
     meta = ctx.obj["config"]["role_path"] / "meta"
+    argument_specs = ""
 
     try:
         argument_specs_yml = list(meta.glob("argument_specs.y*ml"))[0]
-    except IndexError:
-        typer.echo("Could not find meta/argument_specs.yml")
-        raise typer.Exit(code=1)
-
-    with open(argument_specs_yml, "r") as f:
-        try:
-            argument_specs = yaml.safe_load(f)
-        except yaml.YAMLError:
-            typer.echo("Not a valid YAML file: meta/argument_specs.yml")
-            raise typer.Exit(1)
-        try:
-            argument_specs = argument_specs["argument_specs"]
-        except TypeError:
-            typer.echo("Could not read meta/argument_specs.yml")
-            raise typer.Exit(1)
+        with open(argument_specs_yml, "r") as f:
+            try:
+                argument_specs = yaml.safe_load(f)
+            except yaml.YAMLError:
+                typer.echo("Not a valid YAML file: meta/argument_specs.y[a]ml")
+            try:
+                argument_specs = argument_specs["argument_specs"]
+            except TypeError:
+                typer.echo("Could not read meta/argument_specs.y[a]ml")
+    except (UnboundLocalError, IndexError):
+        pass
 
     try:
         main_yml = list(meta.glob("main.y*ml"))[0]
     except:
-        typer.echo("Could not find meta/main.yml")
+        typer.echo("Could not find meta/main.y[a]ml")
         raise typer.Exit(code=1)
 
     with open(main_yml, "r") as f:
         try:
             main = yaml.safe_load(f)
         except yaml.YAMLError:
-            typer.echo("Not a valid YAML file: meta/main.yml")
+            typer.echo("Not a valid YAML file: meta/main.y[a]ml")
             raise typer.Exit(1)
-
+        if not argument_specs:
+            try:
+                argument_specs = main["argument_specs"]
+            except TypeError:
+                typer.echo("Could not read meta/main.y[a]ml or meta/argument_specs.y[a]ml")
+                raise typer.Exit(1)
     return main, argument_specs
 
 
@@ -220,12 +222,13 @@ def gather_choices(path: list[str], arguments: dict) -> list[tuple[list[str], li
     belong to.
     """
     results = []
-    options = arguments["options"]
-    for name, details in options.items():
-        if "choices" in details:
-            results.append((path + [name], details["choices"]))
-        if "options" in details:
-            results.extend(gather_choices(path + [name], details))
+    if "options" in arguments:
+        options = arguments["options"]
+        for name, details in options.items():
+            if "choices" in details:
+                results.append((path + [name], details["choices"]))
+            if "options" in details:
+                results.extend(gather_choices(path + [name], details))
 
     return results
 
@@ -250,11 +253,12 @@ def gather_options(path: list[str], arguments: dict) -> list[tuple[list[str], di
     belong to.
     """
     results = []
-    options = arguments["options"]
-    results.append((path, options))
-    for name, details in options.items():
-        if "options" in details:
-            results.extend(gather_options(path + [name], details))
+    if "options" in arguments:
+        options = arguments["options"]
+        results.append((path, options))
+        for name, details in options.items():
+            if "options" in details:
+                results.extend(gather_options(path + [name], details))
 
     return results
 

aar_doc/templates/markdown.j2

@@ -19,11 +19,13 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 ## Role Arguments
 ---
 {% for entrypoint in argument_specs.keys() %}
-{%- set path, options=entrypoint_options[entrypoint][0] -%}
+
 ### Entrypoint: {{ entrypoint }}
 ---
 {{ argument_specs[entrypoint].short_description }}
 
+{% if entrypoint_options[entrypoint] %}
+{%- set path, options=entrypoint_options[entrypoint][0] -%}
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 {%- for name, details in options.items() %}
@@ -41,6 +43,7 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 {%- endfor %}
 
 {% endfor -%}
+
 {% endif -%}
 {% if entrypoint in entrypoint_choices -%}
 {% for path, choices in entrypoint_choices[entrypoint] -%}
@@ -54,7 +57,14 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 
 {% endfor -%}
 {% endif -%}
+{% else -%}
+
+This entrypoint has no options.
+
+{% endif -%}
+
 {% endfor %}
+
 ## Dependencies
 ---
 {%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
@@ -74,9 +84,14 @@ None.
       ansible.builtin.import_role:
         name: {{ role }}
       vars:
-        {% for name, variable in argument_specs.main.options | items -%}
-        {%- if variable.required | default(false) -%}
-        {{ name }}: # required, type: {{ variable.type }}
+        {%- for entrypoint in argument_specs.keys() -%}
+        {% if entrypoint_options[entrypoint] %}
+        {%- set path, options=entrypoint_options[entrypoint][0] -%}
+        {%- for name, details in options.items() -%}
+        {%- if details.display_required == "yes" | default(false) %}
+        {{ name }}: # required, type: {{ details.display_type }}
+        {%- endif -%}
+        {% endfor -%}
         {%- endif -%}
         {% endfor %}
 ```

tests/fixtures/roles/extended/README.md

@@ -15,6 +15,8 @@ Tags: ansible, docs
 
 ## Role Arguments
 ---
+
+
 ### Entrypoint: main
 ---
 The main entrypoint for the extended role
@@ -44,6 +46,8 @@ The main entrypoint for the extended role
 | 8 |
 | 42 |
 
+
+
 ### Entrypoint: list
 ---
 The list entry point for the extended role.
@@ -54,6 +58,8 @@ The list entry point for the extended role.
 | list_str | A list of strings | list of 'str' | no | ["foo", "bar", "baz"] |
 | list_dict | A list of dicts | list of 'dict' | no | [{"dict": {"foo": "bar"}}, {"dict": {"one": 1, "two": 2}}] |
 
+
+
 ### Entrypoint: dict
 ---
 The dict entry point for the extended role.
@@ -62,6 +68,8 @@ The dict entry point for the extended role.
 |---|---|---|---|---|
 | dict | A dictionary of keys and values | dict | no | {"dict": {"foo": "bar", "one": 1, "two": 2}} |
 
+
+
 ### Entrypoint: dict-with-options
 ---
 The dict-with-options entry point for the extended role.
@@ -84,6 +92,8 @@ The dict-with-options entry point for the extended role.
 |---|---|---|---|---|
 | str | A str value | str | no |  |
 
+
+
 ### Entrypoint: bool
 ---
 The bool entry point for the extended role.
@@ -95,6 +105,8 @@ The bool entry point for the extended role.
 | bool_yes | A truthy boolean value | bool | no | true |
 | bool_no | A falsy boolean value | bool | no | false |
 
+
+
 ### Entrypoint: int
 ---
 The int entry point for the extended role.
@@ -103,6 +115,8 @@ The int entry point for the extended role.
 |---|---|---|---|---|
 | int | An int value | int | no | 1 |
 
+
+
 ### Entrypoint: float
 ---
 The float entry point for the extended role.
@@ -111,6 +125,8 @@ The float entry point for the extended role.
 |---|---|---|---|---|
 | float | A float value | float | no | 1.2 |
 
+
+
 ### Entrypoint: path
 ---
 The path entry point for the extended role.
@@ -119,6 +135,8 @@ The path entry point for the extended role.
 |---|---|---|---|---|
 | path | A path value | path | no | /tmp/foo/bar |
 
+
+
 ### Entrypoint: raw
 ---
 The raw entry point for the extended role.
@@ -128,6 +146,8 @@ The raw entry point for the extended role.
 | raw_str | A raw str value | raw | no | raw |
 | raw_int | A raw int value | raw | no | 123 |
 
+
+
 ### Entrypoint: jsonarg
 ---
 The jsonarg entry point for the extended role.
@@ -136,6 +156,8 @@ The jsonarg entry point for the extended role.
 |---|---|---|---|---|
 | jsonarg | A JSON value | jsonarg | no | {"foo": "bar"} |
 
+
+
 ### Entrypoint: json
 ---
 The json entry point for the extended role.
@@ -144,6 +166,8 @@ The json entry point for the extended role.
 |---|---|---|---|---|
 | json | A JSON value | json | no | {"foo": "bar"} |
 
+
+
 ### Entrypoint: bytes
 ---
 The bytes entry point for the extended role.
@@ -152,6 +176,8 @@ The bytes entry point for the extended role.
 |---|---|---|---|---|
 | bytes | A bytes value | bytes | no | 1.15GB |
 
+
+
 ### Entrypoint: bits
 ---
 The bits entry point for the extended role.
@@ -161,6 +187,7 @@ The bits entry point for the extended role.
 | bytes | A bit value | bits | no | 1Mb |
 
 
+
 ## Dependencies
 ---
 None.

tests/fixtures/roles/inject/README.md

@@ -12,6 +12,8 @@ Test role with some header and footer text outside of the template
 
 ## Role Arguments
 ---
+
+
 ### Entrypoint: main
 ---
 The main entry point for the minimum role.
@@ -22,6 +24,7 @@ The main entry point for the minimum role.
 | myapp_str | The string value | str | yes |  |
 
 
+
 ## Dependencies
 ---
 None.