Feature/generate defaults

.pre-commit-config.yaml

@@ -44,6 +44,7 @@ repos:
           - jinja2
           - typer
           - pyyaml
+          - ruamel.yaml
 
   - repo: https://github.com/pre-commit/mirrors-mypy.git
     rev: v1.11.2

README.md

@@ -1,6 +1,6 @@
 # aar-doc - Automated Ansible Role Documentation
 
-`aar-doc` is a tool for generating documentation automatically from an Ansible role's metadata. Specifically, it reads the `meta/main.yml` and `meta/argument_specs.yml` files.
+`aar-doc` is a tool for generating documentation and defaults automatically from an Ansible role's metadata. Specifically, it reads the `meta/main.yml` and `meta/argument_specs.yml` files.
 
 This is heavily inspired by [terraform-docs](https://github.com/terraform-docs/terraform-docs) which does a similar thing with Terraform modules. `aar-doc` isn't nearly as featureful though, but should do the trick!
 
@@ -18,7 +18,7 @@ pip install aar-doc
 
 ## Usage
 
-```
+```text
  Usage: aar-doc [OPTIONS] ROLE_PATH COMMAND [ARGS]...
 
  A tool for generating docs for Ansible roles.
@@ -46,16 +46,11 @@ pip install aar-doc
 │ --help                                        Show this message and exit.    │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ╭─ Commands ───────────────────────────────────────────────────────────────────╮
+│ defaults   Command for generating role defaults.                             │
 │ markdown   Command for generating role documentation in Markdown format.     │
 ╰──────────────────────────────────────────────────────────────────────────────╯
 ```
 
-### Modes
-
-The `inject` mode will inject only the changed content in between the `BEGIN_ANSIBLE_DOCS` and `END_ANSIBLE_DOCS` markers. This makes it possible to have header and footer text in the file that is not touched. This is the default mode, and will revert to `replace` if the file does not exist to create it the first time.
-
-The `replace` mode will replace the whole file with the template. Usually, the `inject` mode should be fine for regular usage and changing the mode is not necessary unless you want to overwrite an existing file.
-
 ### Configuration
 
 The configuration options can be provided either via CLI arguments shown in `--help`, or a `--config-file` in YAML format. Note that the options have underscores when provided via the configuration file.
@@ -72,7 +67,23 @@ output_file: ROLE.md
 output_mode: replace
 ```
 
-### Templating
+### Defaults
+
+The defaults are written to the `defaults/main.yml` file in your provided role.
+
+If you want to write them to a different file under `defaults/` you can specify that file via the `--output-file` option.
+
+If your `argument_specs` contains an option with a default value multiple times, it will use the first found value and description by default. If you want the value and description to be overwritten, you can use the `--overwrite-duplicates` option.
+
+### Markdown
+
+#### Modes
+
+The `inject` mode will inject only the changed content in between the `BEGIN_ANSIBLE_DOCS` and `END_ANSIBLE_DOCS` markers. This makes it possible to have header and footer text in the file that is not touched. This is the default mode, and will revert to `replace` if the file does not exist to create it the first time.
+
+The `replace` mode will replace the whole file with the template. Usually, the `inject` mode should be fine for regular usage and changing the mode is not necessary unless you want to overwrite an existing file.
+
+#### Templating
 
 You can override the `--output-template` used for rendering the document. This may be passed in as a string containing Jinja2, or a path to a file. As noted above, this option may be passed in via CLI or the configuration file.
 
@@ -103,7 +114,7 @@ Template variables:
 
 Example:
 
-```
+```jinja2
 <!-- BEGIN_ANSIBLE_DOCS -->
 
 This is my role: {{ role }}