[Question] Is the generation of defaults in the scope of the project?

[moritzrp]

Question

First of all, I would like to say that this tool is great and already removes a lot of manual effort. So thank you for the work and effort that is being put into it!

At the moment you still need to manually update the defaults for a role. So updating the meta/argument_specs.yml is not enough. With bigger roles this can take quite some effort. This makes we wonder, would you see it within the scope of the project to implement a command that takes care of this as well?

With that the workflow would be pretty straight forward:

1. Create the meta/argument_specs.yml
2. aar_doc myrole markdown
3. aar_doc myrole defaults

I'm looking forward to hear your feedback on this topic.

P.S. I would be happy to contribute to this as well.

[montaropdf]

Hi @moritzrp,

I am not a maintainer, but, I am not sure to understand your question, could you provide an example?

[moritzrp]

Hey @montaropdf ,

sure, let me give a concrete example:

I have a role "myrole". This role contains the usual meta/main.yml and meta/argument_specs.yml.

Contents of the meta/argument_specs.yml:

---
argument_specs:
  main:
    short_description: Main entry for myrole
    options:
      myrole_foo:
        type: str
        required: false
        default: some_foo
        description: foo
      myrole_bar:
        type: str
        required: true
        description: bar
  alternate:
    short_description: Alternate entry for myrole
    options:
      myrole_baz:
        type: str
        required: false
        default: some_baz
        description: baz
      myrole_qux:
        type: str
        required: true
        description: qux

Since the meta/argument_specs.yml contains our defaults already, I am after is something like aar_doc myrole defaults.

This could generate the defaults/main.yml:

---
myrole_foo: some_foo

And defaults/alternate.yml:

---
myrole_baz: some_baz

But this is not strictly documentation and has some different behavior than the current file generation.

So the question is from my side: Does this fit into the project from the maintainers perspective? Or is this simply not what the project is intended for?

[montaropdf]

ok, I see, now. Could be nice, but indeed not sure this is the point of the project.

However, you should be able to achieve what you want with a custom template, maybe.

[rndmh3ro]

I like the idea!

And defaults/alternate.yml:

This won't work, as Ansible only reads defaults/main.yml or defaults/main/*.yml (and then all files in this folder).

However, you should be able to achieve what you want with a custom template, maybe.

I just tested this and in general this works, but there are some problems:

• <!-- BEGIN_ANSIBLE_DOCS --> and <!-- END_ANSIBLE_DOCS --> are displayed in the defaults.yml - they need to go.
• there are some problems with type-conversion, e.g. the umask "0755" is defined as a string but will be output as an integer, tripping up ansible-lint
• same goes for strings like "yes" and "no" that get converted to booleans, but that's just python for you..
• dictionary-variables are not displayed nicely:
  • sysctl_config: {"fs.protected_hardlinks": 1, "fs.protected_symlinks": 1, "fs.protected_fifos": 1, "fs.protected_regular": 2, "fs.suid_dumpable": 0, "kernel.core_uses_pid": 1, "kernel.kptr_restrict": 2, "kernel.kexec_load_disabled": 1, "kernel.sysrq": 0, "kernel.randomize_va_space": 2, "kernel.yama.ptrace_scope": 1}

Here's the jinja I used:

{% for entrypoint in argument_specs.keys() %}
{% if entrypoint_options[entrypoint] %}
{%- set path, options=entrypoint_options[entrypoint][0] -%}
{%- for name, details in options.items() %}
# {{ details.display_description | wordwrap(78) | replace('\n', '\n# ') }}
# type: {{ details.display_type }}
{{ name }}: {{ details.display_default }}
{% endfor %}

{% endif -%}

{% if entrypoint_options[entrypoint] | length > 1 -%}
{% for path, options in entrypoint_options[entrypoint][1:] -%}
{%- for name, details in options.items() %}
{{ details.display_description.comment | wordwrap(78) | replace('\n', '\n# ') }}
{{ name }}: {{ details.display_default }}
{% endfor %}

{% endfor -%}
{% endif -%}
{% endfor -%}

So I guess its easier to achieve this with Python that with Jinja.

P.S. I would be happy to contribute to this as well.

Looking forward to a MVP for this. :) Though we probably then need to rename the project. :)

[moritzrp]

Great! Then I will start experimenting with this to find a solution :)

[moritzrp]

Alright the MVP is done. I made sure not to touch the existing structure and just added a new self contained command for now.

So now you have aar-doc ROLE_PATH defaults. By default, this will generate the ROLE_PATH/defaults/main.yml file.

Since --output-file is somewhat specific to docs, I added an option directly to the new command. If you want to write to a different file you can use aar-doc ROLE_PATH defaults --defaults-file /foo/bar/my_defaults.yml.

But this is mainly a placeholder for the test cases. I think in general the commands could be adjusted to have specific options for either generating docs or defaults.

Summary of what it does:

• Goes through all entry points in the argument_specs and collects options with default values => If a later entry point configures an option with the same name it will be overwritten!
• Writes all collected defaults to ROLE_PATH/defaults/main.yml. If you specify a different file, it simply writes to said file.
• If the output file already exists, it will be overwritten!

As for the formatting of the output file:
The styling can be adjusted. For now the options are simply hard coded. What we can do:

• default_style: Currently left default. Can be set to literal block, folded block, double-quoted or single-quoted.
• allow_unicode: Currently set to True.
• sort_keys: Currently set to False. So we have the same order as in the argument_specs.
• indent: Currently set to 2.
• encoding: Currently set to utf-8

All of these could also be controlled by the configuration or by an option passed along to the command.

If you want to see an example of what it produced, you can take a look at the argument_specs.yml and resulting defaults/main.yml from the added test case.

This is just the starting point. If you have any comments or suggestions for the behavior, I am of course happy to discuss it.

[moritzrp]

Closing this since this topic was handled in #81.