document objects

[oliver-sanders]

We should reference "objects" in documentation rather than using inline-literals.

For instance rather than:

This is configured in the ``[scheduling]`` section.

We should do:

This is configured in the :cylc:conf:`[scheduling]` section.

Benefits of doing this:

• Integrity checking, the docs will fail to build if a configuration is removed, but still referenced in the docs.
• Hyperlinks, all references to cylc sections result in hyperlinks to the relevant content.
• Consistency of appearance.

This applies to more than just cylc configuration items:

• Python modules / functions:
  • e.g: :py:mod:'cylc.flow.health_check'.
  • For this to work the python module must be included in the docs somewhere.
• Environment variables:
  • e.g. :envvar:'CYLC_TASK_NAME'.
  • This requires environment variables to be documented (not yet done)
• Cylc commands:
  • e.g. :program:'cylc run', :option:'--detach'
  • This requires commands to be auto-documented (not yet done)

[kinow]

I'm impressed by the amount of study I need for Sphinx. Lots to learn. That apart, your argument sounds good, +1. Though I can't promise accidentally using the old syntax for a while until I remember to use objects instead :)