Check Config Documentation for items over-ridden in workflow config

[wxtim]

Checks

• Ensure that in all cases where config items are present in global.cylc and over-ridden in flow.cylc that there are references in both configs to the other, but a full description in only one.
  • For example, abort handlers, which only has a link from global config to workflow, and not vice-versa.
• Add an explanation to [runtime][__task__][remote] and [job] sections are only used to select a platform. Remove any suggestion that they over-ride other configs.

Decision making paper trail

From #4896 (comment):

... Dave and I have had a discussion about this, which we've not documented, but we have it in mind to go through all these cases: I think the agreement was that there should be:

• A headline description [both]
• A fuller description [only one config]
• A link to the other conifg [both]

Pull requests welcome!

This is an Open Source project - please consider contributing a bug fix
yourself (please read CONTRIBUTING.md before starting any work though).

[MetRonnie]

I'm assuming no longer blocked as #4848 has been merged

[MetRonnie]

Ensure that in all cases where config items are present in global.cylc and over-ridden in flow.cylc that there are references in both configs to the other, but a full description in only one.

In practice this means writing the full description as a variable in globalcfg.py and importing that into workflow.py (has to be this way round to avoid circular imports). The full description is split on \n\n to get the one-liner actually used as the description in globalcfg.py. Note that this loses admonitions like .. versionchanged and .. warning, but it was decided in today's team catchup that we'd accept this in the interests of concision.

[MetRonnie]

Split off #4915 from this