Merge pull request #71 from telekom-mms/feature/examples_in_docs

Feature/examples in docs

.gitignore

@@ -10,3 +10,5 @@ htmlcov
 .coverage
 coverage.xml
 dist
+
+.venv

aar_doc/templates/markdown.j2

@@ -1,5 +1,5 @@
 # Ansible Role: {{ role }}
----
+
 {%- if "version" in galaxy_collection %}
 Version: {{ galaxy_collection.version }}
 {% endif %}
@@ -9,19 +9,19 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 {%- endif %}
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 {%- for platform in metadata.galaxy_info.platforms %}
 | {{ platform.name }} | {{ platform.versions | default([]) | join(', ') }} |
 {%- endfor %}
 
 ## Role Arguments
----
+
 {% for entrypoint in argument_specs.keys() %}
 
 ### Entrypoint: {{ entrypoint }}
----
+
 {{ argument_specs[entrypoint].short_description }}
 
 {% if entrypoint_options[entrypoint] %}
@@ -35,7 +35,7 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 {% if entrypoint_options[entrypoint] | length > 1 -%}
 {% for path, options in entrypoint_options[entrypoint][1:] -%}
 #### Options for {{ path | join(" > ") }}
----
+
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 {%- for name, details in options.items() %}
@@ -45,10 +45,11 @@ Tags: {{ metadata.galaxy_info.galaxy_tags | join(', ') }}
 {% endfor -%}
 
 {% endif -%}
+
 {% if entrypoint in entrypoint_choices -%}
 {% for path, choices in entrypoint_choices[entrypoint] -%}
 #### Choices for {{ path | join(" > ") }}
----
+
 |Choice|
 |---|
 {%- for item in choices %}
@@ -63,10 +64,17 @@ This entrypoint has no options.
 
 {% endif -%}
 
+{%- if "examples" in argument_specs[entrypoint] -%}
+
+#### Examples
+
+{{ argument_specs[entrypoint].examples }}
+
+{%- endif -%}
 {% endfor %}
 
 ## Dependencies
----
+
 {%- if ("dependencies" in metadata) and (metadata.dependencies | length > 0) %}
 {%- for dependency in metadata.dependencies %}
 - {{ dependency }}
@@ -76,7 +84,7 @@ None.
 {%- endif %}
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -97,11 +105,11 @@ None.
 ```
 
 ## License
----
+
 {{ metadata.galaxy_info.license }}
 
 ## Author and Project Information
----
+
 {%- if "company" in metadata.galaxy_info %}
 {{ metadata.galaxy_info.author }} @ {{ metadata.galaxy_info.company }}
 {%- else %}

tests/fixtures/roles/extended/README.md

@@ -1,24 +1,23 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 # Ansible Role: extended
----
 Test role with lots of metadata
 
 Tags: ansible, docs
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 | Fedora | all |
 | Debian | all, bullseye, bookworm, wheezy |
 | Cumulus | 2.5 |
 
 ## Role Arguments
----
+
 
 
 ### Entrypoint: main
----
+
 The main entrypoint for the extended role
 
 |Option|Description|Type|Required|Default|
@@ -31,25 +30,32 @@ The main entrypoint for the extended role
 | default_type | Type is str by default | str | no |  |
 
 #### Choices for main > choices-str
----
+
 |Choice|
 |---|
 | one |
 | two |
 | three |
 
 #### Choices for main > choices-int
----
+
 |Choice|
 |---|
 | 1 |
 | 8 |
 | 42 |
 
+#### Examples
+
+this is an example how to execute the entrypoint:
+
+    - hosts: all
+      roles:
+        - extended
 
 
 ### Entrypoint: list
----
+
 The list entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -61,7 +67,7 @@ The list entry point for the extended role.
 
 
 ### Entrypoint: dict
----
+
 The dict entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -71,31 +77,31 @@ The dict entry point for the extended role.
 
 
 ### Entrypoint: dict-with-options
----
+
 The dict-with-options entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | opts | A dictionary of keys and values | dict of 'opts' options | no |  |
 
 #### Options for dict-with-options > opts
----
+
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | int | An int value | int | no | 1 |
 | json | A JSON value | json | no | {"foo": "bar"} |
 | subopts | A sub-dictionary of keys and values | dict of 'subopts' options | no |  |
 
 #### Options for dict-with-options > opts > subopts
----
+
 |Option|Description|Type|Required|Default|
 |---|---|---|---|---|
 | str | A str value | str | no |  |
 
 
 
 ### Entrypoint: bool
----
+
 The bool entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -108,7 +114,7 @@ The bool entry point for the extended role.
 
 
 ### Entrypoint: int
----
+
 The int entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -118,7 +124,7 @@ The int entry point for the extended role.
 
 
 ### Entrypoint: float
----
+
 The float entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -128,7 +134,7 @@ The float entry point for the extended role.
 
 
 ### Entrypoint: path
----
+
 The path entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -138,7 +144,7 @@ The path entry point for the extended role.
 
 
 ### Entrypoint: raw
----
+
 The raw entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -149,7 +155,7 @@ The raw entry point for the extended role.
 
 
 ### Entrypoint: jsonarg
----
+
 The jsonarg entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -159,7 +165,7 @@ The jsonarg entry point for the extended role.
 
 
 ### Entrypoint: json
----
+
 The json entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -169,7 +175,7 @@ The json entry point for the extended role.
 
 
 ### Entrypoint: bytes
----
+
 The bytes entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -179,7 +185,7 @@ The bytes entry point for the extended role.
 
 
 ### Entrypoint: bits
----
+
 The bits entry point for the extended role.
 
 |Option|Description|Type|Required|Default|
@@ -189,11 +195,10 @@ The bits entry point for the extended role.
 
 
 ## Dependencies
----
 None.
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -205,11 +210,10 @@ None.
 ```
 
 ## License
----
+
 MIT
 
 ## Author and Project Information
----
 your name @ ansible-docs
 
 Issues: [tracker](https://gitlab.com/kankare/ansible-docs/-/issues)

tests/fixtures/roles/extended/meta/argument_specs.yml

@@ -11,6 +11,12 @@ argument_specs:
     author:
       - Foo
       - Bar
+    examples: |
+      this is an example how to execute the entrypoint:
+
+          - hosts: all
+            roles:
+              - extended
     options:
       name:
         option-name: override

tests/fixtures/roles/inject/README.md

@@ -1,21 +1,20 @@
 <!-- BEGIN_ANSIBLE_DOCS -->
 # Ansible Role: inject
----
 Test role with some header and footer text outside of the template
 
 
 ## Requirements
----
+
 | Platform | Versions |
 | -------- | -------- |
 | Fedora | all |
 
 ## Role Arguments
----
+
 
 
 ### Entrypoint: main
----
+
 The main entry point for the minimum role.
 
 |Option|Description|Type|Required|Default|
@@ -26,11 +25,10 @@ The main entry point for the minimum role.
 
 
 ## Dependencies
----
 None.
 
 ## Example Playbook
----
+
 ```
 - hosts: all
   tasks:
@@ -42,11 +40,10 @@ None.
 ```
 
 ## License
----
+
 MIT
 
 ## Author and Project Information
----
 your name @ ansible-docs
 
 <!-- END_ANSIBLE_DOCS -->