# 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](https://github.com/ansible/ansible/issues/75054).