Userguide overhaul

[hjoliver]

Cranking through a pre-8.0 full User Guide check 😫 ...

Companion to #310

Close #248

• update any remaining Cylc 7 bits
• make various bits of excessive verbiage more clean and concise

[oliver-sanders]

Nice to cut out some of the lengthier sections of cruft.

Some small issues and test failures to fix.

[oliver-sanders]

What's the status of the reflow example above?

Can we now document a basic "reflow" workflow (something like start/pause/play/stop)?

[hjoliver]

Yes, I'll try to document that today, as well as optional outputs.

[oliver-sanders]

Bumped to a separate issue - #335

[hjoliver]

Thanks for the early review @oliver-sanders - some things you noted were due to this still being an in-process Draft, but mostly very useful (and time is of the essence right now!)

[hjoliver]

Have now cleaned up most of the "Running Workflows" "Writing Workflows" -> "Runtime" section, which was a real mess 😬

[hjoliver]

(And rebased onto master, to pick up changes from my previous PR)

[hjoliver]

"Writing Workflows" section almost done now. Turns out, getting through the whole thing in one day was , erm, over-optimistic. 😭

[hjoliver]

Undrafted. Let's get what we can in for the final beta. (I have a little more to do as noted in Element chat, but that could be a follow up).

[oliver-sanders]

👍

[oliver-sanders]

Note, I think we can use the Cylc UI test framework (Cypress) to auto-generate screenshots of UI components e.g. the task/job state key when we get the time.

[MetRonnie]

Partial review

[MetRonnie]

Ongoing review

[MetRonnie]

Suggested change

	The scheduler can only check for lateness once a task has appeared in its
	active task window. In Cylc 8 this is usually when the task is actually
	ready to run, which severely limits the usefulness of late events as
	currently implemented.
	The scheduler can only check for lateness once a task has appeared in its
	active task window. In Cylc 8 this is usually when the task is actually
	ready to run, which severely limits the usefulness of late events as
	currently implemented.

[hjoliver]

Sphinx doesn't mind, right? Is 3 spaces a convention we've agreed on?

[hjoliver]

(applied anyway, as it does look a bit nicer in the source file)

[oliver-sanders]

Is 3 spaces a convention we've agreed on

Yes.

When we started the cylc-doc we inherited the convention from rose (http://metomi.github.io/rose/doc/html/developing/restructuredtext.html) e.g. heading order =, -, ^ which tried to use the prevailing conventions. These are still the prevailing conventions, more or less.

Sphinx doesn't mind, right.

Depends on the version! Mixed indentation did cause us issues in the past when upgrading Sphinx version.

(I think Sphinx might now be going beyond the ReST spec to make things more user friendly now, not sure.)

ReST is highly sensitive to indentation, this is by design, some things might work but not generate the result you intended.

Safer and easier to stick to the prevailing convention.

...

Long answer to aforementioned quibbles since you raised it...

Directives

Directive form 1:

.. directive:: arg1 arg2
   :opt1: value1
   :opt2: value2

   content

Directive form 2:

.. directive::
   arg1
   arg2
   :opt1: value1
   :opt2: value2

   content

Admonitions

In this case the content is actually passed to the directive as an argument.

.. note::
   content

I think Sphinx has some logic to handle this for admonitions, however, it will break other directives so safer to be consistent.

Indentation

"Natural indentation" should be used i.e subsequent lines should align with the start of previous lines, so:

* foo
  bar (2 space)

1. foo
   bar (3 space)

.. directive::

   content (3 space)

Blockquotes and .. code

Code and blockquotes are indentation sensitive:

Paragraph::

   Code example

Paragraph

   Blockquote

Example: Malformed directive:

.. directive::

  two space indented content

Should this be:

<directive>
  content
</directive>

Or:

<directive />
<blockquote>
  content
</blockquote>

???

Example: Mixed indentation (someone came along later and edited or added to a directive):

.. directive::

   content (3 spaces)

  more content (2 spaces)

Same ambiguity as before but worse.

Note there is a line reset character, I think its |, I'm not sure if its a ReST or a Sphinx feature though which muddies the water somewhat.

Bullets and definition lists

.. two bullet lists NOT connected

* one
* two
* three

* one
* two
* three

.. two definition lists NOT connected

foo
   foo
bar
   bar
baz
   baz

foo
   foo
bar
   bar
baz
   baz

Arbitrary white-space matters here.

Headings

Heading order is based on definition order so the following two examples are both correct:

H1
===

H2
---

H3
^^^

H1
^^^

H2
---

H3
===

This is confusing as heck so keep to convention!

Note Sphinx likes threes, three space indent, and three character minimum for heading underlines!

[MetRonnie]

@oliver-sanders Is it worth adding that to CONTRIBUTING.md?

[oliver-sanders]

Yeah, in a slightly more refined form.

I think this is in the Sphinx docs and in the rose/developing page (I think the rose dev pages are a little out of date).

[MetRonnie]

Ongoing review

[MetRonnie]

The placement of this versionadded admonition disrupts the example that is being shown imho

[MetRonnie]

Is there not a replacement for this section?

[hjoliver]

I don't think its necessary really. Python (for instance) doesn't bother to document why it doesn't have built in storage and revision control for Python programs - it should be obvious to users. And it seems to me we shouldn't be recommending Rose for the job until some future git-based version, knowing that everyone (even UM Partners) has moved away from svn outside of the MOSRS.

[hjoliver]

@MetRonnie - hopefully good to go now 🤞

[MetRonnie]

🚀

[oliver-sanders]

Good pending some minor points (will push changes and get this in!).

[oliver-sanders]

Bumped to a separate issue - #335

[oliver-sanders]

Is 3 spaces a convention we've agreed on

Yes.

When we started the cylc-doc we inherited the convention from rose (http://metomi.github.io/rose/doc/html/developing/restructuredtext.html) e.g. heading order =, -, ^ which tried to use the prevailing conventions. These are still the prevailing conventions, more or less.

Sphinx doesn't mind, right.

Depends on the version! Mixed indentation did cause us issues in the past when upgrading Sphinx version.

(I think Sphinx might now be going beyond the ReST spec to make things more user friendly now, not sure.)

ReST is highly sensitive to indentation, this is by design, some things might work but not generate the result you intended.

Safer and easier to stick to the prevailing convention.

...

Long answer to aforementioned quibbles since you raised it...

Directives

Directive form 1:

.. directive:: arg1 arg2
   :opt1: value1
   :opt2: value2

   content

Directive form 2:

.. directive::
   arg1
   arg2
   :opt1: value1
   :opt2: value2

   content

Admonitions

In this case the content is actually passed to the directive as an argument.

.. note::
   content

I think Sphinx has some logic to handle this for admonitions, however, it will break other directives so safer to be consistent.

Indentation

"Natural indentation" should be used i.e subsequent lines should align with the start of previous lines, so:

* foo
  bar (2 space)

1. foo
   bar (3 space)

.. directive::

   content (3 space)

Blockquotes and .. code

Code and blockquotes are indentation sensitive:

Paragraph::

   Code example

Paragraph

   Blockquote

Example: Malformed directive:

.. directive::

  two space indented content

Should this be:

<directive>
  content
</directive>

Or:

<directive />
<blockquote>
  content
</blockquote>

???

Example: Mixed indentation (someone came along later and edited or added to a directive):

.. directive::

   content (3 spaces)

  more content (2 spaces)

Same ambiguity as before but worse.

Note there is a line reset character, I think its |, I'm not sure if its a ReST or a Sphinx feature though which muddies the water somewhat.

Bullets and definition lists

.. two bullet lists NOT connected

* one
* two
* three

* one
* two
* three

.. two definition lists NOT connected

foo
   foo
bar
   bar
baz
   baz

foo
   foo
bar
   bar
baz
   baz

Arbitrary white-space matters here.

Headings

Heading order is based on definition order so the following two examples are both correct:

H1
===

H2
---

H3
^^^

H1
^^^

H2
---

H3
===

This is confusing as heck so keep to convention!

Note Sphinx likes threes, three space indent, and three character minimum for heading underlines!

[hjoliver]

Test fail is unrelated:

error: can't copy 'metomi/rose/etc/tutorial/rose-weather-forecasting-suite/bin': doesn't exist or not a regular file

All review suggestions applied.