Semantic Markup for plugins

tags: Documentation

Summary

Community Ansible documentation wants to add semantic markup within the module/plugin DOCUMENTATION strings. This gives all projects that use ansible-doc --json output improved flexibility on how to display this information. These projects include Automation Hub, ansible-navigator, possibly the vscode plugin, and the collection_prep script used by some certified collection owners.

Business Justification

By separating what the content is (environment variable, option, value) from how we display it (bold, color, italics) we provide the ability of products such as Automation Hub to visually enhance the display for improved readability of this information.

By formalizing this semantic markup, we also provide the ability to:

• Create CI tests that validate the information at the point of creation.
• Maintain consistency across collections. (Today, one content creator could decide to mark a module option in bold while another content creator can mark it as italics.) This creates inconsistencies in how the information displays across certified collections and products that lowers the presumed 'quality' of the information.
• Create more embedded links between information. Today, if a module mentions a particular option, there is no way we can link directly to that option. With semantic markup, we can create those links so that a reader can click and learn what that option means and how to use it.
• Show tooltips which provide more information on the option (type, beginning of description, link to full documentation) when the user hovers over a mention of them.

Primary goal - To improve the visual aid that helps readers determine what the differences are in such a way that is consumable by other products that display module information (such as Automation Hub).​

Solution - Introduce a light level of semantic markup, where the collection creator 'marks' the content for what it is (environment variable, value, option, etc) instead of how it should display (bold, italics, monospace, etc), and that contains more contextual information (which plugin this is an option of, if referring to an option of another plugin/module). This leaves the visual aspect independent and up to the product how to display it. For example - Automation Hub could use bold, italics, or could add colors to the display to enhance the reader's experience.

Markup Specification

The community decided on the following additions:

• O(key) and O(key=value) for option names, with or without values
  • The following forms of O(...) are allowed and provide the ability for CI validation and hotlinks:
  1. O(name) or O(name=value) for a top-level option name of the current plugin/module;
  2. O(name.sub) or O(name.sub=value) for a suboption sub of the top-levle option name of the current plugin/module; if you have sub-sub-options, use O(name.sub.subsub) etc;
  3. The same as 1 or 2, but with [] for options or suboptions, for example O(name[]) or O(name.sub[]=value) or O(name[].sub), to indicate that some of the options or suboptions refer to lists. The [] can also contain other text that's not a ], for example O(name[len(all_names)-1].foo[0]). This text will be ignored for validation purposes;
  4. O(FQCN#type:name) or O(FQCN#type:name=value) for a top-level option name of the plugin/module FQCN (for example, ansible.builtin.uri) of plugin type type (one of module, lookup, …, role);
  5. O(FQCN#type:name.sub.subsub) or O(FQCN#type:name.sub.subsub=value) with potential []s for a sub-sub-option subsub of a sub-option sub of a top-level option name of the plugin/module FQCN (for example ansible.builtin.uri) of plugin type type (one of module, lookup, …, role);
  6. The same as 4 and 5, but with [] for options or suboptions, with the same rules as in 3;
  7. The FQCN variants (4 to 6) are needed to reference options in other plugins/modules; to reference options in the current plugin/module, variants 1 to 3 can be used. The FQCN is needed both for creating links, and for validating (ansible-test's validate-modules sanity check).
• V(value) for standalone option values
• E(env_var) for environment variables
• P(FQCN#plugintype) for plugin references
• RV(name) or RV(name=value) for return values, with similar allowed forms as used by O(name), i.e. RV(FQCN#type:name.sub.subsub) and RV(FQCN#type:name.sub[].subsub=value). (For example, for facts returned by another plugin, one can use RV(FQCN#type:ansible_facts.name.sub.subsub).)

Values in the above forms (the text following = in O() and RV(), and the whole text in V()) can use \ to escape ), \\ to escape \. This allows to write expressions that contain ), which is not possible the current markup (C(), I() and B()).

Existing markup macros will remain, including:

• M(FQCN) for module references
• C(code) for other monospace text such as linux commands
• B(boldtext) and I(italic_text) for other words or phrases an author wants to emphasize.

These added macros may impact other projects, such as Galaxy-ng/Automation Hub, ansible-navigator, possibly the vscode plugin, and the collection_prep script used by some collections to generate local rst docs files.

Extension to "See Also"

The current seealso: section in the module/plugin documentation allows to provide references to modules, URLs, and RST references. To reference a plugin, you have to use its RST reference, but that will not work on other platforms (for example Automation Hub/Galaxy). So similarly to adding P(...#...), we propose to add a new seealso type:

seealso:
  - plugin: (FQCN of plugin)
    plugin_type: (type of plugin)
    description: (optional description)

Simiarly to a module entry, the description is optional. For FQCN and plugin type the same values are allowed as for P(FQCN#plugintype).

Background

This started with a general dissatisfaction on how some of the module options and parameters are displayed on docs.ansible.com (what is bold, what is italics, monospace, etc) and the inherent inflexibility of our current markup options.

The upstream proposal is at https://github.com/ansible-community/community-topics/issues/53

WIP examples:

• https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_set_module.html#parameters
• https://ansible.fontein.de/collections/community/dns/hetzner_dns_record_sets_module.html#parameters

For more complete details and WIP PRs, see ansible/ansible#75054.