Conf tree

[oliver-sanders]

These changes close #3253

Sibling PRs:

• Conf tree cylc-sphinx-extensions#22
• Conf tree cylc-doc#121

Highlights:

• Define the "specification" for the suite and global configurations using "context nodes".
• Copy documentation in from cylc-doc (documentation will require review at a later date).

Other Stuff:

• Port some functional tests to pytest.
• Port some unittest to pytest.
• Remove some unnecessary escape chars from the old RST docs.

Todo:

• Add metavars for __MANY__ items.
• Open a cylc-doc PR to autodocument this.

Future work:

• Consider changing the options list to a dictionary.
• Refactor the deprecation mechanism around the new configuration nodes.
• Review all documentation and configurations!!!
• Build examples into the parsec validator types.
  • Saves us having a PT1H example in every config which takes a duration as an arugment.
• Use SPEC items for retrieving config values (e.g. self.config(SPEC['scheduling']['initial cycle point'])
  • Allows us to detect when we are still relying on deprecated configs in Cylc.
  • Allows us to add hyperlinks to the reference material in error messages.
• Update all references configurations in the docs to use the :cylc:conf'[a][b]c' syntax.
  • Allows integrity checking of the documentation.
  • Gives you hyperlinks to the relevant sections.
  • Allows referencing of Cylc configurations from other Sphinx project (e.g. Rose).

Context Node Fun:

>>> from cylc.flow.cfgspec.suite import SPEC

>>> print(SPEC.tree())
    [meta]
        description
        group
        title
        URL
        __MANY__
    [cylc]
        UTC mode
        cycle point format
        cycle point num expanded year digits
...

>>> for conf in SPEC['scheduling']: print(repr(conf))
[scheduling]initial cycle point
[scheduling]final cycle point
[scheduling]initial cycle point constraints
...

Requirements check-list

• I have read CONTRIBUTING.md and added my name as a Code Contributor.
• Contains logically grouped changes (else tidy your branch by rebase).
• Does not contain off-topic changes (use other PRs for other changes).
• Appropriate tests are included (unit and/or functional).
• Appropriate change log entry included.
• (master branch) I have opened a documentation PR at Conf tree cylc-doc#121

[oliver-sanders]

An early example of what the built documentation will look like (using the default Sphinx theme)

And more:

With the Read The Docs theme it will look more like the rose API.

http://metomi.github.io/rose/doc/html/api/configuration/application.html#rose:file:rose-app.conf

[wxtim]

An early example of what the built documentation will look like (using the default Sphinx theme)

Is this example based on the code in this branch? If so, how?

[datamel]

An early example of what the built documentation will look like (using the default Sphinx theme)

Is this example based on the code in this branch? If so, how?

Once built, this snippet can be found in Docs » Reference » Configuration » Suite Configuration

[datamel]

Run ahead limit already documented a couple of lines up (line 252)

[oliver-sanders]

Configs gets alphabetically sorted before rendering the output in Sphinx so these two won't appear next to each other in the final docs.

[datamel]

-huh? ...is that supposed to be there?

[oliver-sanders]

Probably not! Unless it was special emphasis.

[datamel]

I have now built the docs, looks great. Minor suggestions across the 3 prs.

[oliver-sanders]

Thanks for putting up the typos as suggestions, made things much easier :)

[kinow]

Tested with the cylc-doc PR.