Add some more documentation on command template

[ioguix]

Hi,

We have been poking around to be able to add some DSL code as argument in a command template. We thought it would be useful to add some more doc about it as it might be useful to some others.

This is a first shot, let me know what you think and if it needs some rewording, syntax fix, etc.

[rndmh3ro]

Hi @ioguix,

I like the changes! Though you need to change the : with . in the examples since that wouldn't be valid yaml-code.

Also this documentation could be added to the command module, right?

[ioguix]

I like the changes! Though you need to change the : with . in the examples since that wouldn't be valid yaml-code.

Yes, I saw this in the auto-checks :/
Thank for the fix.

I'm not used to the module format and documentation, but I wondered if the choices/comments cells could be split in some way to reflect the various types the arguments key can takes, but haven't found a clean way to do it.

I'm not sure adding multiple arguments keys with different type, comment and suboptions would be supported either.

Any opinion on this?

[ioguix]

oh, I forgot to answer:

Also this documentation could be added to the command module, right?

Maybe, but really I don't know. I hadn't dig for the command module as we didn't bump on it. In fact, I was secretly hopping someone more experienced with the module would chime in and confirm this applies to the command module as well :)

[rndmh3ro]

Maybe, but really I don't know. I hadn't dig for the command module as we didn't bump on it. In fact, I was secretly hopping someone more experienced with the module would chime in and confirm this applies to the command module as well :)

I just checked, the command has arguments that look the same from the frontend view and the API, so we can add it there, too.

I'm not used to the module format and documentation, but I wondered if the choices/comments cells could be split in some way to reflect the various types the arguments key can takes, but haven't found a clean way to do it.

Good question, I don't know either.

The API seems to differ only in that the value is either a string or a dict:

with a string:

    "arguments": {
        "test": {
            "command_id": "848",
            "skip_key": false,
            "value": "foo"
        }
    },

with a dict:

    "arguments": {
        "test": {
            "command_id": "848",
            "skip_key": false,
            "value": {
                "type": "Function",
                "body": "foo"
            }
        }
    },

So we could build the module in a way that when the type of the value of the argument is "Function", it gets the type and body. If it is not a "Function", we skip the type and body and just add the string to the value argument. Makes sense?

However I don't really know if I WANT that. :D

[ioguix]

So we could build the module in a way that when the type of the value of the argument is "Function", it gets the type and body

I don't get it. I was speaking of the doc generation/format itself. In this context, I'm not sure I understand your answer, sorry :/

[rndmh3ro]

I don't get it. I was speaking of the doc generation/format itself. In this context, I'm not sure I understand your answer, sorry :/

Well, the docs do have to match the actual configuration! :)

We currently define the the arguments variable takes a dict as an argument: https://github.com/T-Systems-MMS/ansible-collection-icinga-director/blob/a37201aec640f21d0ae33638b121a83f5fc93848/plugins/modules/icinga_command_template.py#L196

Now the actual arguments variable not only takes a dict as input but a string as well. However Ansible provides no native way to say that this variable can be a string or a dict (for me that's rather a problem with the Icinga-API). So we'd need to set the variable to raw and then check if it is actually a dict or string with our own logic.

And even then we probably could not display this correct in the docs since the docs have to match the implementation.

What you want for the documentation is something like this, right? https://docs.ansible.com/ansible/latest/collections/community/docker/docker_container_module.html#parameter-healthcheck

[ioguix]

Now the actual arguments variable not only takes a dict as input but a string as well

...or a json according to the code. But I don't know if/how ansible is dealing with this.

What you want for the documentation is something like this, right?

Well, these are suboptions if I understood correctly, they are related to a key of type dict, taking...sub options :)
But yes, I was thinking about something similar, but for the columns choices and comments. As far as I can see, this is not possible, so I suppose the current patch proposal is good enough.

Thanks!

[rndmh3ro]

Thanks for this!

I created https://github.com/T-Systems-MMS/ansible-collection-icinga-director/issues/130 to follow up on this.

[ioguix]

Thanks!