cylc8 first-pass #148

oliver-sanders · 2020-08-17T16:09:21Z

Sibling PRs: cylc/cylc-sphinx-extensions#29, cylc/cylc-flow#3777

A quick first-pass of the documentation:

Reference configurations properly (:cylc:conf:).
Fix some Cylc7/8 changes.
Remove some obsolete documentation.
Make code examples fix the suite design guide.
Auto-document more stuff from Cylc Flow.
Simplify some wording.
Correct some syntax highlighting.
Consistently capitilise Cylc (except the cylc command).
Merge "architecture" in with the "introduction" to allow the intro section to grow.

This started out as a quick pass to use the cylc-domain e.g. [runtime] -> :cylc:conf:'[runtime]', however, it is very hard to edit just one thing in the documentation at the moment :/

The Grand Scheme Of Things:

This isn't the "great edit" that the docs need, however, it should make that edit a bit easier when it comes.

These docs aren't polished ready for release, however, they are a bit better than before.

Most of the non-indentation changes are in the user guide, namely writing and running suites.

Pre 8.0.0:

Here's a non-exhaustive list of stuff to do to the docs pre-cylc8:

Terminology changes (e.g. suite->flow).
Platformise stuff after the [platforms] changes.
Review the configuration documentation in cylc-flow.
Review all the docs ;)
Fix the tutorial to Cylc8 changes.
Write a Cylc7->8 transition guide.
Fix the screenshots as well as all graph / GUI references.
Amend installation instructions as they change + write quickstart.
Break apart some of the monolithic sections (e.g. writing / running suites) into more digestible parts.

oliver-sanders · 2020-08-17T16:12:46Z

Tests will fail until the next version of cylc-sphinx-extensions is released and the sibling Cylc Flow PR is merged.

To review, checkout the cylc-flow and cylc-sphinx-extensions branches and pip install them.

MetRonnie · 2020-08-17T16:47:02Z

src/glossary.rst

-      the ``suite.rc`` file.
+      the :cylc:conf:`suite.rc` file.


Stuff like this is going to conflict every single time with my suite.rc --> flow.cylc PR #142 😅

We'll try to get yours in first then!

@oliver-sanders - you're deliberately not ditching the term "suite" in this PR?

For now yes. Ronnies change should be merged soon so I'll get the rebase! We will need a separate PRs to eradicate "suite" references in cylc-flow/cylc-doc as this is a big job in of itself.

src/user-guide/writing-suites.rst

hjoliver

A good start to the big rewrite 👍 Approved with a few minor suggestions. (And one grump about indentation inside script strings ... but I'll stop flogging that dead horse now ... also for consistency reasons as we've ended with mixed styles at this point).

cylc/doc/etc/tutorial/retries-tutorial/suite.rc

src/glossary.rst

hjoliver · 2020-08-17T23:34:15Z

src/glossary.rst

-      the ``suite.rc`` file.
+      the :cylc:conf:`suite.rc` file.


@oliver-sanders - you're deliberately not ditching the term "suite" in this PR?

src/glossary.rst

hjoliver · 2020-08-17T23:40:46Z

src/introduction/how-cylc-works.rst

-`GNU General Public License v3.0
-<https://www.gnu.org/licenses/gpl-3.0.en.html>`_.
-
-
 .. [1] Future plans for EcoConnect include additional deterministic regional
       weather forecasts and a statistical ensemble.
 .. [2] Note that simply overlapping the single cycle point schedules of the


Should delete this whole file. It is way out of date (especially now, post-SoD)

Fair enough, it's full of NWP context too, happy to remove the content and leave the title or else leave the whole thing pending re-write.

Let's remove it.

src/user-guide/remote-job-management.rst

hjoliver · 2020-08-17T23:59:14Z

src/user-guide/running-suites.rst


 - task-to-suite messaging via TCP (using ZMQ protocol)
- task-to-suite messaging via non-interactive SSH to the suite host,
-  then local TCP


Didn't we decide we need to restore this capability?

Yes, however, we haven't restored it yet (I think still waiting on a decision over whether we can rely on TCP forwarding or whether we should re-implement the Cylc7 SSH-forwarding logic).

Pretty sure we decided we had to re-implement the old logic - ping @dpmatthews ? Maybe bang a TODO in here at least, so we don't forget to come back and update this section.

Yes, I think we've decided to use the old method. See cylc/cylc-flow#3327.

src/user-guide/suite-storage-etc.rst

src/user-guide/writing-suites.rst

oliver-sanders · 2020-08-18T09:42:49Z

Obviously, don't merge this branch until the tests pass.

oliver-sanders · 2020-08-19T16:35:57Z

Added an extra couple of commits onto the end.

I'm not quite sure what happened here but it looks like the migration of extensions into cylc-sphinx-extensions was never properly completed. I must have been in a rush. There were some static files left behind in src/_static.

This was covering up a much bigger issue to do with the installation of static files. Sadly the approach being used to install the static files by fiddling the static_html_path project configuration no longer works. Sphinx doesn't let you fiddle the project config from extensions any more, which, to be fair, makes sense.

So I've added a commit onto the end of cylc/cylc-sphinx-extensions#29 which manually copies static files across into the build directory. It would appear that this is the only real way to do it, this is what other extensions do.

MetRonnie · 2020-08-19T17:45:39Z

Tried to test by checking out all the relevant branches on this, cylc-flow and cylc-sphinx-ext but the conf changes are making it a headache, Can we merge #142 first?

Co-authored-by: Hilary James Oliver <hilary.j.oliver@gmail.com> Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>

oliver-sanders · 2020-08-21T11:59:30Z

Rebased and deconflicted, tests should now pass (at long last!).

oliver-sanders · 2020-08-21T12:05:36Z

... Or not, linkcheck failure still to fix...

oliver-sanders · 2020-08-21T12:40:18Z

Ok, I think it's nearly there, just one last linkcheck issue which requires yet another PR cylc/cylc-flow#3783

MetRonnie · 2020-08-21T15:35:49Z

I've tested this with the right branches checked out and it passes. Don't know if you want to wait for the other branches before merging

oliver-sanders · 2020-08-21T15:41:31Z

I'll wait for the cylc flow branch to be merged and the actions run to pass.

oliver-sanders · 2020-08-24T08:33:39Z

Tests pass, took a few PRs to cylc-sphinx-extensions, cylc-doc and cylc-flow, but we are now Sphinx3, [platforms] and *.cylc compliant.

oliver-sanders · 2020-08-24T08:34:31Z

Merging with two approvals.

oliver-sanders self-assigned this Aug 17, 2020

oliver-sanders added the content Addition or modification of documentation label Aug 17, 2020

oliver-sanders mentioned this pull request Aug 17, 2020

auto-document cylc modules cylc/cylc-flow#3777

Merged

7 tasks

MetRonnie self-requested a review August 17, 2020 16:40

MetRonnie reviewed Aug 17, 2020

View reviewed changes

src/user-guide/writing-suites.rst Outdated Show resolved Hide resolved

hjoliver approved these changes Aug 18, 2020

View reviewed changes

oliver-sanders commented Aug 18, 2020

View reviewed changes

src/user-guide/writing-suites.rst Show resolved Hide resolved

MetRonnie approved these changes Aug 18, 2020

View reviewed changes

oliver-sanders force-pushed the cylc-domain-references branch from 44d9214 to be1e0e9 Compare August 19, 2020 16:31

oliver-sanders mentioned this pull request Aug 19, 2020

practical: add a tutorial directive cylc/cylc-sphinx-extensions#29

Merged

oliver-sanders force-pushed the cylc-domain-references branch from be1e0e9 to 1dad293 Compare August 20, 2020 16:23

oliver-sanders mentioned this pull request Aug 21, 2020

Change suite.rc to flow.cylc #142

Merged

oliver-sanders added 13 commits August 21, 2020 12:28

c8 first-pass: glossary

29ca41f

c8 first-pass: writing-suites

053a5f1

c8 first-pass: running suites

136d2e3

c8 first-pass: suite storage

0f0ae04

c8 first-pass: task implementation

ba7b4ac

c8 first-pass: task-job submission

07e8de6

c8 first-pass: remote job mgmt

3d4ab19

c8 first-pass: external triggers

9c4845f

suite server program -> scheduler

11bbcfe

remove double space period

1cf8271

merge introduction and architecture sections

d2ba82c

implement suite design guide in code examples

909028a

cylc-scope: use the configured default

b0dcd7c

oliver-sanders and others added 5 commits August 21, 2020 12:48

double space

25dc902

Apply suggestions from code review

4daff63

Co-authored-by: Hilary James Oliver <hilary.j.oliver@gmail.com> Co-authored-by: Ronnie Dutta <61982285+MetRonnie@users.noreply.github.com>

extensions: use cylc-sphinx-extensions static resources

0b9a613

version: fix version bug with .dev releases

b56c506

suite.rc -> flow.cylc, flow.rc -> global.cylc

b4034ec

oliver-sanders force-pushed the cylc-domain-references branch from 1dad293 to b4034ec Compare August 21, 2020 11:59

fix links

9125726

MetRonnie approved these changes Aug 21, 2020

View reviewed changes

oliver-sanders merged commit 7ba8037 into cylc:master Aug 24, 2020

oliver-sanders deleted the cylc-domain-references branch August 24, 2020 08:34

MetRonnie linked an issue Aug 27, 2020 that may be closed by this pull request

Platforms: update docs #145

Closed

MetRonnie mentioned this pull request Aug 27, 2020

Platforms: update docs #145

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

cylc8 first-pass #148

cylc8 first-pass #148

oliver-sanders commented Aug 17, 2020 •

edited

Loading

oliver-sanders commented Aug 17, 2020 •

edited

Loading

MetRonnie Aug 17, 2020 •

edited

Loading

oliver-sanders Aug 17, 2020

hjoliver Aug 17, 2020

oliver-sanders Aug 18, 2020 •

edited

Loading

hjoliver left a comment

hjoliver Aug 17, 2020

hjoliver Aug 17, 2020

oliver-sanders Aug 18, 2020

hjoliver Aug 18, 2020

hjoliver Aug 17, 2020

oliver-sanders Aug 18, 2020

hjoliver Aug 18, 2020

dpmatthews Sep 10, 2020

oliver-sanders commented Aug 18, 2020

oliver-sanders commented Aug 19, 2020 •

edited

Loading

MetRonnie commented Aug 19, 2020

oliver-sanders commented Aug 21, 2020

oliver-sanders commented Aug 21, 2020

oliver-sanders commented Aug 21, 2020

MetRonnie commented Aug 21, 2020

oliver-sanders commented Aug 21, 2020

oliver-sanders commented Aug 24, 2020

oliver-sanders commented Aug 24, 2020

cylc8 first-pass #148

cylc8 first-pass #148

Conversation

oliver-sanders commented Aug 17, 2020 • edited Loading

oliver-sanders commented Aug 17, 2020 • edited Loading

MetRonnie Aug 17, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliver-sanders Aug 18, 2020 • edited Loading

Choose a reason for hiding this comment

hjoliver left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

oliver-sanders commented Aug 18, 2020

oliver-sanders commented Aug 19, 2020 • edited Loading

MetRonnie commented Aug 19, 2020

oliver-sanders commented Aug 21, 2020

oliver-sanders commented Aug 21, 2020

oliver-sanders commented Aug 21, 2020

MetRonnie commented Aug 21, 2020

oliver-sanders commented Aug 21, 2020

oliver-sanders commented Aug 24, 2020

oliver-sanders commented Aug 24, 2020

oliver-sanders commented Aug 17, 2020 •

edited

Loading

oliver-sanders commented Aug 17, 2020 •

edited

Loading

MetRonnie Aug 17, 2020 •

edited

Loading

oliver-sanders Aug 18, 2020 •

edited

Loading

oliver-sanders commented Aug 19, 2020 •

edited

Loading