questions regarding parsing of requirements and dict variables

[psych0d0g]

i would try to create a custom template to get requirement roles documented in the readme.md aswell,
ansible galaxy works using a requirements.yml in the meta folder of a role with the following syntax:

- src: [email protected]:package-roles/package.git
  version: main
- src: [email protected]:package-roles/firewall.git
  version: main
- src: [email protected]:package-roles/php.git
  version: main

any idea how one could archive that?

another question revolves around dictionary variables, and how to properly get doctor to detect them and document them.
currently its just this:

# @var apache2_listen_ports:type: dictionary
# @var apache2_listen_ports:description: >
# if the https port is omitted, the default vhost will only listen on http
# otherwise a redirect is included in the vhost that redirects http requests to https
# @end
apache2_listen_ports:
  http: 80
  https: 443

and doctor itself would also only detect the initial dict var, is there a way to have it split them out, and detect and document the keys in the dict as vars aswell?

[xoxys]

I'm a bit confused by what exactly you try to achieve.

i would try to create a custom template to get requirement roles documented in the readme.md aswell

ansible-doctor does not parse any requirements.yml file, It's intended to be used for roles or collections. According to the docs, both don't include requirements.yml files. To link and document dependencies of roles you can add it to the meta file as described in the ansible roles docs. Dependencies from the meta file will be detected and documented automatically.

another question revolves around dictionary variables, and how to properly get doctor to detect them and document them.
currently its just this

Not sure if I understand this question. The type of an Ansible variable doesn't matter for ansible-doctor. It will detect the variable, document the default and all additional information added by annotations. It's not possible to add annotations or additional information to the keys of a dict variable. But you could add an example annotation:

# @var apache2_listen_ports:example: >
# apache2_listen_ports:
#   # Description of the http key
#   http: 80
#   # Description of the https key
#   https: 443
# @end

The result looks like this:

[psych0d0g]

thank you for the answer, ansible-galaxy is picking up requirements.yml defined requirements from roles automatically and installs them aswell when you place a requirement.yml into the meta directory, its diffrent from dependencies since they are not rolled out automatically with that aproach, but can be delegated to within your roles flow of tasks with ansible.builtin.include_role:.
that way you have more control over the roles and their execution.
for example i have an apache and a php role, the apache role has a variable that en- or disables the apache2_mod_php component, and also delegates further php setup to the php role if enabled, from within the apache role like so:

- name: ensure php is setup and installed as needed
  ansible.builtin.include_role:
    name: php
  vars:
    php_implementation:
      apache: true
      cli: false
      fpm: false

for that to work i either need to put both roles into the requirements.yml of my playbooks, or, and that is what i am doing, put the php role into the requirements.yml of my apache role, and only tell my playbook it needs apache

[psych0d0g]

for the variable section, i would love if it would be possible to have doctor resolve nested / sublayers of dictionary variables.
basically instead of detecting apache2_listen_ports as the only var in that block maybe detect something like apache2_listen_ports.http and apache2_listen_ports.https in this case

[xoxys]

From reading the docs https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#dependencies both methods meta/main.yml and meta/requirements.yml should work exactly the same. Where can I find information about the different behavior?

[xoxys]

for the variable section, i would love if it would be possible to have doctor resolve nested / sublayers of dictionary variables.

Sorry, this is IMO a bit out of scope.

[psych0d0g]

From reading the docs https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#dependencies both methods meta/main.yml and meta/requirements.yml should work exactly the same. Where can I find information about the different behavior?

thats not correct, if you check a few paragraphs below (https://docs.ansible.com/ansible/latest/galaxy/user_guide.html#using-meta-main-yml), it states:

Dependencies installed that way, depending on other factors described below, will also be executed **before** this role is executed during play execution

whereas if you define dependency in meta/requirements.yml they are not executed automatically, just installed, so that they can be executed at a controlled point in the role.

the main difference here i think is meta/main.yml dependencies are an ansible-core feature:
https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#using-role-dependencies

whereas the meta/requirements.yml is "just" instructions for ansible-galaxy to make sure those dependencies listed there are installed if the role is pulled in through a playbooks requirements.yml via ansible-galaxy.
and galaxy happens to also understand the ansible-core meta/main.yml dependencies to make sure those roles are installed aswell.

the differing part is probably that the requirements.yml is only parsed by galaxy and ansible itself has no idea about it or its contents

[xoxys]

Thanks for the details, I think I understand your use case. Would you like to contribute the meta/requirements.yml parsing feature?

[psych0d0g]

i am open to looking into contributing that feature, just gonna need some time to slice off my general schedules to poke around ;)
ill get back to you in the next 1-2 weeks i think :)

[xoxys]

No worries 🙂 if you have any question just let me know.