search

thegeeklab / ansible-doctor

Annotation based documentation for your Ansible roles
https://ansible-doctor.geekdocs.de
GNU General Public License v3.0
129 stars 20 forks source link

Add option to define arbitrary annotations #785

Open pat-s opened 2 weeks ago

pat-s commented 2 weeks ago

It looks like the sub-types are hard-coded in https://github.com/thegeeklab/ansible-doctor/blob/080b31773821e22b7c136981e040d6212ce3d25e/ansibledoctor/config.py#L37. Adding another one to a custom template is not getting picked up by the parser.

In case I am right and it is not possible - would be a great feature :)

xoxys commented 2 weeks ago

That is correct, and I don't think we should allow adding user-defined ones. Maybe you can explain your use-case a bit more. In general, Ansible roles and collections should be self-explaining anyway, and the project was meant to be used to add some useful context that can be rendered out to an overview page. If you have pretty complex roles, writing a detailed documentation from scratch might be the better choice.

xoxys commented 2 weeks ago

Implementing https://github.com/thegeeklab/ansible-doctor/issues/763 might help as well, but also doesn't allow arbitrary fields.

pat-s commented 2 weeks ago

I wanted to add another column that shows whether a variable is required or optional. I document both variables in the variable table (i.e. also the ones that are not defined). I prefer not defining them instead of setting them to "" as I like to use the is defined pattern. Hence, I add them to defaults/main.yml and comment them out (but still add tags for them so that they get processed by ansible-doctor). TBH I was missing this for a long time in ansible and think that the lack of a proper documentation skeleton is a big downside (hence I was very happy to stumble across ansible-doctor now - just need to tweak it a bit ;)).

While I could also add this information implicitly inside the variable name itself somehow, having a dedicated table that lists both required and optional vars with a column stating this respectively, seems like a good default.

I understand that it is not feasible to add custom columns every now and then, also everyone might have a different opinion on naming etc. So allowing to specify them in an array in a custom template seems like a good solution?