Make order of options from argument_specs.yml configurable

[dansou901]

Summary

When docs for ansible roles with argument_specs.yml files are built, the options of the argument_specs are always displayed in alphabetical order in the output html. Sometimes it would be better to be able to specify a different order, for example with deeply nested parameter structures.

To solve this problem, I propose that a new configuration option in argument_specs should be introduced to be able to configure the order. One option should be to configure it so the output html will be ordered the same as it is written in the argument_specs.yml. The other (default) option should be to leave it in alphabetical order.

Thoughts?

Additional Information

No response

[felixfontein]

The only two tools I am aware of that render argument_specs.yml are ansible-doc (part of ansible-core) and antsibull-docs. Both tools always sort options (and sub-options and return values etc.) alphabetically. The only exception are positional arguments for test and filter plugins when rendered by antsibull-docs, these are in the order specified (there is a field positional in DOCUMENTATION for that).

One option should be to configure it so the output html will be ordered the same as it is written in the argument_specs.yml.

Right now antsibull-docs obtains the documentation for plugins, modules, and roles from the ansible-doc JSON output, in which every dictionary is sorted by key name.

[felixfontein]

Ignoring the above, I like the idea of being able to group options by topic. Especially roles can have a large amount of options, due to many things that can be fine-tuned.

On the other hand, one could also argue that things that require too many inputs are not well designed and should be broken up into smaller parts.

And there's also the argument that allowing to specify the order freely would allow roles to have a messy order that makes it harder for folks to find what they are looking for. (Which was one of the reasons why the options are ordered by alphabet - I think they weren't always; at least the ones for modules.)

[briantist]

I would definitely second a way for grouping options by topic, and not just for roles.

The community.hashi_vault collection is another example; there are a lot of options in each plugin and module because they come from shared module utils and doc fragments. But the resulting docs are all over the place since the options from each auth method all mix together along with the shared connection options and module/plugin-specific options, so it's really messy and hard to follow.

Grouping would be perfect for this.

[dansou901]

Yes, grouping would be fine. Inside the groups the parameters then can be sorted alphabetically again, the groups themselves should also have some kind of identifier/name.
So, at the level of the key options in argument_specs, there should be a key named e. g. option_groups. This should be a list of group names (array of strings). Then, inside of each option, there will be a key named option_group, which has then to contain one of the option_groups defined above. Inside of the option_groups, options should be sorted alphabetically again. The option_groups themselves can also be sorted alphabetically.

[samccann]

From the WG meeting: - This one requires core involvement, and probably first a proper proposal - especially if it should also cover plugins and modules (cause of docs fragments)

[mariolenz]

This issue looks stale, so let's close it. If it's something we should work on, I suggest to open a topic in the forum.