Include, rather than write in, significant code examples

[sadielbartholomew]

We should aim towards moving all significant chunks of hard-written code out of the .rst content files, & (if not located already in a known place, as in e.g. #65) into a separate dedicated directory as individual files, where they would be written into the built docs from the relevant file by the literalinclude: directive.

This would have various benefits, for example it would:

• ensure that code snippets written out in the docs are up-to-date &/or consistent with codebase code they are referring to (as in e.g. Update echo xtrigger in line with current (Python 3) code #65);
• allow us to validate such code for correctness, & against deprecation, certain blocks, notably suite.rc examples;
• enable us to keep track of the number of code examples, & in turn to reference the figure accurately on the Cylc website as a major asset of the docs, & generally as a positive indicator for quality of project.

[kinow]

That sounds like a good idea. I suspect it might be a bit boring the whole copy-paste process to get the code out of the documentation.

There is an issue in cylc-sphinx-extensions that I think is related to this issue: cylc/cylc-sphinx-extensions#8

[sadielbartholomew]

There is an issue in cylc-sphinx-extensions that I think is related

Ooh, good spot. Thanks for noting that.

I suspect it might be a bit boring the whole copy-paste process

Yes, you are right there! But not everything can be fun &/or interesting, sadly 😁

[oliver-sanders]

There is an issue in cylc-sphinx-extensions that I think is related to this issue: cylc/cylc-sphinx-extensions#8

FYI on the validation front it's actually kinda tricky as most code examples are actually snippets which aren't necessarily valid workflows.

[sadielbartholomew]

FYI on the validation front it's actually kinda tricky as most code examples are actually snippets which aren't necessarily valid workflows.

True, good point. But we should certainly aim to validate all of the full suite.rc snippets, & other self-contained logical aspects such as graph strings. In future, we could even develop a set of regular expressions etc. to check for correct & up-to-date syntax for some elements in snippets & bare lines, or for valid section headings from a list, etc. Perhaps a bit OTT, but it would be nice.

[matthewrmshin]

Solving cylc/cylc-flow#2392 may help.