Feature/generate defaults

[moritzrp]

This PR addresses #77 by adding a new command to generate defaults.

[rndmh3ro]

Thanks for your work! I took your comments from issue #77 and discuss them here:

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.

• I'd like to have only one option, --output-file for this. I don't see a need to have output-file and defaults-file.
• the options output_template and output_mode should then be moved to the markdown command, since they're specific to this command

---

If a later entry point configures an option with the same name it will be overwritten!

• Fine for me I think, though this should be documented

---

Writes all collected defaults to ROLE_PATH/defaults/main.yml. If you specify a different file, it simply writes to said file.

• should we use yaml or yml? Or detect the presence of either one and use it, if it exists? Seems best from a user perspective for me

---

The styling can be adjusted. For now the options are simply hard coded [...] All of these could also be controlled by the configuration or by an option passed along to the command.

• let's do this if there's a need from someone. :)

---

When there are no options in the entrypoint, there's an error. We need a test for this and a fix. You can run the defaults command on the role tests/fixtures/roles/no_options/ to see the problem.

---

How about we add the description as comments atop the variables? ruamel.yaml can do this with yaml_set_comment_before_after_key, though I didn't try it yet.

---

There are some mypy and pylint-errors. If you use pre-commit locally, you'll get basic linting and tests.

> poetry run pylint aar_doc/
************* Module aar_doc.cli
aar_doc/cli.py:32:4: W1113: Keyword argument before variable positional arguments list in the definition of increase_indent function (keyword-arg-before-vararg)
aar_doc/cli.py:32:0: W0613: Unused argument 'args' (unused-argument)
aar_doc/cli.py:32:0: W0613: Unused argument 'kwargs' (unused-argument)
aar_doc/cli.py:83:4: W0621: Redefining name 'defaults' from outer scope (line 69) (redefined-outer-name)
aar_doc/cli.py:196:39: W0621: Redefining name 'defaults' from outer scope (line 69) (redefined-outer-name)
aar_doc/cli.py:470:4: W0621: Redefining name 'defaults' from outer scope (line 69) (redefined-outer-name)

> poetry run mypy aar_doc/
aar_doc/cli.py:196: error: Function "builtins.any" is not valid as a type  [valid-type]
aar_doc/cli.py:196: note: Perhaps you meant "typing.Any" instead of "any"?
aar_doc/cli.py:206: error: Name "output" already defined on line 203  [no-redef]
aar_doc/cli.py:464: error: Function "builtins.any" is not valid as a type  [valid-type]
aar_doc/cli.py:464: note: Perhaps you meant "typing.Any" instead of "any"?
Found 3 errors in 1 file (checked 2 source files)

[moritzrp]

There are some mypy and pylint-errors. If you use pre-commit locally, you'll get basic linting and tests.

Thanks for the hint! I completely missed the pre-commit config.

How about we add the description as comments atop the variables? ruamel.yaml can do this with yaml_set_comment_before_after_key, though I didn't try it yet.

I like the idea. It makes the defaults a lot clearer without having to reference the argument_specs. I will check out what needs to be done and how it plays with pyyaml being used.

should we use yaml or yml? Or detect the presence of either one and use it, if it exists? Seems best from a user perspective for me

I agree here as well. I think we could use what the user defined for theirmeta/main.yml and go with that extension. Otherwise, for the non-automated way, ansible-galaxy role init seems to be generating .yml by default. So personally, I would go with that.

---

As for the other topics, I will move the options and add the missing test case. I would also start adapting the README so it covers what is changed.

[rndmh3ro]

I will check out what needs to be done and how it plays with pyyaml being used.

Pyyaml and ruamel.yaml are im my experience mostly compatible, so swapping out PyYAML for ruamel.yaml should be possible.

I agree here as well. I think we could use what the user defined for theirmeta/main.yml and go with that extension. Otherwise, for the non-automated way, ansible-galaxy role init seems to be generating .yml by default. So personally, I would go with that.

Agree. I just checked my locally existing Ansible-code and main.yml had 312 occurences, main.yaml only 7.

One last thing: if you want to (no need!), you could try moving the defaults and markdown code into separate files and subfolders - I think it makes sense now.

[moritzrp]

One last thing: if you want to (no need!), you could try moving the defaults and markdown code into separate files and subfolders - I think it makes sense now.

I'm glad you mention this actually. I was thinking about it since the cli.py is getting quite busy. But without the go ahead I didn't want to restructure parts that are not part of the feature 😄.

But I agree, it makes sense to have a defaults module and a markdown module.

[rndmh3ro]

@moritzrp, if the PR is ready, you can set it to ready.

[moritzrp]

Hey @rndmh3ro , now the most most parts are done from my side.

the options output_template and output_mode should then be moved to the markdown command, since they're specific to this command

This is still open. Moving the options (and adjusting the test cases) still somehow breaks the test_output_template and the test_expand_home_path test case. At the moment I have no idea why that is.

The options have no negative effects on the defaults command. So from my side it would be fine to go without it for now. To change it I need to spend some time debugging what is going on there.

It's not specific to other changes I made. If you move the options on the main branch the same thing will happen.

[moritzrp]

Alright, now I am happy. I overlooked some changes from ruamel.yaml and finished up the structure.

[rndmh3ro]

Thanks for this PR! Awesome work.

I'll do a follow-up PR shortly to address some things that you can then review.

[schurzi]

Thank you, awesome work!