Doc overhaul

[hjoliver]

Attempting to knock the docs into shape as minimally and quickly as possible pre final beta release.

This PR should:

• upgrade deprecated syntax
• correct outright errors
• make some sections more clear and concise
• remove obsolete stuff (e.g. suicide triggers)
• warn users where screenshots of the old desktop GUIs are still used
• document new capabilities we've missed so far, if time allows, or else warn about what's still to be documented

Done:

• migration guide
• installation section
• tutorial section

Will punt to other PRs:

• main user guide
• workflow design guide
• reference section
• glossary

[oliver-sanders]

Good so far.

[oliver-sanders]

???

[hjoliver]

In the bin directory is a script called get-observations. This script gets weather data from the MetOffice DataPoint service.

Also

$ rose tutorial runtime-tutorial

$ rose tutorial api-key

So not really a standalone Cylc practical??

and

[oliver-sanders]

All of the tutorials used the rose tutorial command to safe people having to set up directories, copy files and all that stuff. For the "runtime" tutorial copying the files manually would be far too slow.

When we transferred the tutorials from Rose we transferred the tutorial files into this repo too, however, we do not presently have a Cylc alternative to the rose tutorial command.

• The files are now in this repo e.g: https://github.com/cylc/cylc-doc/blob/master/cylc/doc/etc/tutorial/api-keys
• They can be accessed via GH-Pages e.g: https://cylc.github.io/cylc-doc/nightly/html/_static/tutorial/api-keys
• Or if cylc-doc is installed they are included in the package e.g: Path(cylc.doc.__file__.parent) / 'etc/api-keys'
• The related issue is here: Cylc Tutorial Suite #40

This script gets weather data from the MetOffice DataPoint service

The DataPoint service was used for the Cylc forecasting tutorial, API keys for accessing the service are bundled with the suite so it is accessible to all. At the time DataPoint was the best offering that we could use without requiring users to setup accounts and so on. We will need to replace DataPoint soon as it is deprecated. We need point wind observations and a rainfall radar-like product. WOW may provide an answer but would require users to setup API keys etc.

[hjoliver]

Undrafted - this can be reviewed and merged as-is, I'll do the user guide etc. next, separately.

[oliver-sanders]

<rst_epilog>:18:Duplicate explicit target name: "jupyter server".

[hjoliver]

The related issue is here: #40

Ah thanks, I'd forgotten about that whole conversation (2 years ago 😬 )

[hjoliver]

The last commit comments out inclusion of the rose tutorial sections, pending #40

OK?

[hjoliver]

Also updated the beta software warning on the main index page.

[oliver-sanders]

Note: The installation step will fail until the cylc-rose and cylc-uiserver PRs updating the setup.cfg files are merged.

[wxtim]

It's not currently building properly for me:

?/cylc-doc/src/tutorial/runtime/configuration-consolidation/index.rst: WARNING: document isn't included in any toctree
?/cylc-doc/src/tutorial/runtime/introduction.rst: WARNING: document isn't included in any toctree
?/cylc-doc/src/tutorial/runtime/runtime-configuration.rst: WARNING: document isn't included in any toctree

Otherwise seems reasonable.

[oliver-sanders]

(caused by #310 (comment))

[hjoliver]

OK, latest commit restores the tutorial sections with warnings. On closer inspection, they probably are still useful.

[oliver-sanders]

Version conflict to be fixed by #312

(note the tests build against project master branches which are now diverging from 8.0b3)