How to handle environment variables?

[felixfontein]

With semantic markup, we have E(...) to reference environment variables. For RST output, the Sphinx :envvar: role is used (https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-envvar). antsibull-docs uses the .. envvar:: directive (https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-envvar) for all environment variables that appear in env: plugin configs (and the Ansible/ansible-core docsite generates .. envvar:: directives for all ansible-core config values, see https://github.com/ansible/ansible/blob/devel/docs/templates/config.rst.j2#L223-L248). But for all other environment variables mentioned in text, there is no such (auto-generated) target.

So either collections define their own targets, which can cause problems if multiple collections define targets that end up in the Ansible docsite, or they don't, and we end up with a list of WARNING: 'envvar' reference target not found: warnings. A good example is ansible-collections/community.docker#645 with its output https://github.com/ansible-collections/community.docker/actions/runs/5235637304/jobs/9452611330.

This makes using E(...) inattractive or even outright impossible (for example in community.docker, the docsite build must have no errors for CI to pass). Manually defining .. envvar:: directives is not a good idea either (except in special cases). #75 would improve the situation a bit, but it won't happen anytime soon (core doesn't like it).

I'm opening this issue so we can discuss what to do about this. Having a huge amount of new reference errors in the docsite build is something I'm pretty sure nobody wants. Just muting all these warnings (the one for env vars, not the general reference errors) isn't a good idea either IMO.

[felixfontein]

One idea: convert E(...) to the :envvar: role only for environment variables that antsibull-docs or ansible-core generates a .. envvar:: directive for (and give collections an escape hatch to tell antsibull-docs that they have their own .. envvar:: directives in the extra docsite docs). For others use a :ansenvvarwotarget: role that formats them the same, but doesn't add a reference.

[felixfontein]

Another idea: collect all environment variables from all markup, and make sure that .. envvar:: directives are created for these. Unfortunately there is not much that can be said there, so you would have a large page with hundrets of environment variable definitions which basically only lists the environment variable name and some standard text "This is an environment variable. Nothing more here.". I don't really like that... I prefer there to be no link when there's nothing good to link to, which Sphinx does when the reference target does not exist - but then Sphinx also outputs that warning (which is also not what we want).

[felixfontein]

(https://ansible.fontein.de/collections/environment_variables.html is an example of a per-docsite autogenerated list of envvar directives; it copies the text from the options that have that environment variable listed in env:, and references back to these options. This was added in #73.)

[samccann]

so are you saying this option is what you show at https://ansible.fontein.de/collections/environment_variables.html ?

[felixfontein]

@samccann your first link points to the wrong target.

[samccann]

Sorry - does the example page that lists all env variables the result of option 2.

[felixfontein]

Yes, it would be something similar. The problem is that it would be just a long list of the environment variable names with no information for them (or just the same text everywhere, saying there is no more information), since we don't know what to show there.

[felixfontein]

I've implemented option one in #166.