[Bug] aar_doc does not support arguments_spec in meta/main.yaml

[montaropdf]

Description

As I do not plan to support ansible < 2.11, I write the argument_specs section into the meta/main.yaml file of my roles. Unfortunately aar_doc does not seem to support that, as I get the following error message:
Could not find meta/argument_specs.yml

Reproduction steps

1. Write a valid argument_specs section in the meta/main.yaml file of a role
2. Do not create a meta/argument_specs.yml
3. Run aar_doc ROLE_PATH markdown to create a markdown documentation

Current Behavior

The tool will generate the following message and produce no markdown output.

Could not find meta/argument_specs.yml

Expected Behavior

If the file ROLE_PATH/meta/argument_specs.yml does not exists, the tool should look into ROLE_PATH/meta/main.yaml for the argument_specs section.

Additional information

aar_doc version: 1.0.4

[rndmh3ro]

see #68

[montaropdf]

As I think this will block any testing of the patch, I want to mention that the markdown.j2 template is hardcoded in the markdown command. Moreover, that template expect to find a subsection main in the argument_specs section, which is not mandatory as far as I know.

At least in my case, it will fails because I have no main subsection.

[rndmh3ro]

As I think this will block any testing of the patch, I want to mention that the markdown.j2 template is hardcoded in the markdown command.

That's not really relevant, as the final output will be parsed using the output_template-option.

Moreover, that template expect to find a subsection main in the argument_specs section, which is not mandatory as far as I know.

That is indeed a problem. I'll try to think about it.

[rndmh3ro]

I removed the main-entrypoint from the markdown file so this should be working for you now.

[montaropdf]

I removed the main-entrypoint from the markdown file so this should be working for you now.

Great, I will test it asap.

Regarding the output_template option, in my previous tests, it doesn't seem to be used, at least with the markdown command. However, I do not rule out the fact I didn't use the option correctly.

[montaropdf]

A first test shows that section argument_specs can be found in meta/main.yaml and meta/argument_specs can be missing.

I noticed, however, that the tool requires the options node of an entry-point to be present. However, some of my entry-points does not require any input variables.

[rndmh3ro]

I noticed, however, that the tool requires the options node of an entry-point to be present. However, some of my entry-points does not require any input variables.

Should be fixed, too! :)

Regarding the output_template option, in my previous tests, it doesn't seem to be used, at least with the markdown command. However, I do not rule out the fact I didn't use the option correctly.

Just tested it again, works for me.

[montaropdf]

With your fix, the documentation is generated when the options node is missing too.

Regarding the use of templates.

I have created a configuration file with the following content:

---
output_template: |
  <!-- BEGIN_ANSIBLE_DOCS -->

  This is my role: {{ role }}

  <!-- Including files is also possible in relation to the role's directory with Jinja2's include directive -->
  {% include "defaults/main.yml" %}

  <!-- 'argument_specs' contains all the things in meta/argument_specs.yml -->
  {% for entrypoint, specs in argument_specs | items %}
  Task file name: {{ entrypoint }}.yml has {{ specs | length }} input variables!
  {% endfor %}
  <!-- END_ANSIBLE_DOCS -->

And use it with the following command:
python -m aar_doc.cli --output-file someoutput.md --config-file=/path/to/configuration/file/config.yaml /path/to/role markdown

Unfortunately, the generated file has the same content as without the configuration file.

[rndmh3ro]

I opened a new issue for your problem: #69

[rndmh3ro]

Fixed by #68