Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

cfg: document recurrence graph addition in config #4066

Merged
merged 1 commit into from Feb 12, 2021
Merged

cfg: document recurrence graph addition in config #4066

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
39 changes: 35 additions & 4 deletions cylc/flow/cfgspec/suite.py
View file
Open in desktop
Expand Up @@ -534,12 +534,43 @@
Example Recurrences:

date-time cycling:
``T00,T06,T12,T18`` or ``PT6H`` - *every six hours*
* ``R1`` - once at the intial cycle point
* ``T00,T06,T12,T18`` - daily at 00:00, 06:00, 12:00
& 18:00
* ``PT6H`` - every six hours starting at the initial
cycle point
integer cycling:
``P2`` - *every other cycle*
* ``R1`` - once at the intial cycle point
* ``P2`` - every other cycle
* ``P3,P5`` - every third or fifth cycle
Comment on lines 536 to +545
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you build this as is the formatting of integer cycling and date-time cycling is the same as that for config item.

Suggested change
date-time cycling:
``T00,T06,T12,T18`` or ``PT6H`` - *every six hours*
* ``R1`` - once at the intial cycle point
* ``T00,T06,T12,T18`` - daily at 00:00, 06:00, 12:00
& 18:00
* ``PT6H`` - every six hours starting at the initial
cycle point
integer cycling:
``P2`` - *every other cycle*
* ``R1`` - once at the intial cycle point
* ``P2`` - every other cycle
* ``P3,P5`` - every third or fifth cycle
date-time cycling:
* ``R1`` - once at the intial cycle point
* ``T00,T06,T12,T18`` - daily at 00:00, 06:00, 12:00
& 18:00
* ``PT6H`` - every six hours starting at the initial
cycle point
integer cycling:
* ``R1`` - once at the intial cycle point
* ``P2`` - every other cycle
* ``P3,P5`` - every third or fifth cycle

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think that's a regression bug in the rtd theme, I seem to remember seeing an issue a while back, I thought it got fixed.

Your diff above converts the bullet point lists into block quotes. Would rather keep the RST correct and fix the rendering bug if possible.

definition list item:
    definition list description

plain text:

   blockquote

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here's the bug issue - readthedocs/sphinx_rtd_theme#800

It was fixed a while back but seems to be back, though in a slightly different form. Will try and find out if this is a design decision.

Just found this which may be somewhat related readthedocs/sphinx_rtd_theme#979 which is open.

Here's the intended appearance - https://sphinx-rtd-theme--981.org.readthedocs.build/en/981/demo/lists_tables.html#definition-lists

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Digging a little deeper I think it is because the definition list is being documented within a domain.

Take this example:

Foo
   foo
Bar
   bar
Baz
   baz


.. py:class:: pub

   Arguments:
      foo: abc
      bar: bcd
      baz: def

   Foo
      foo
   Bar
      bar
   Baz
      baz

Which renders like this:

Screenshot 2021-02-12 at 12 37 55

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep that's it.

However the definition style is still inconsistent with the others.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Raised an issue - readthedocs/sphinx_rtd_theme#1052


See :ref:`GraphTypes` for more on recurrence expressions, and
how multiple graphs combine.
.. note::

Unlike other Cylc configurations duplicate recurrences
are additive and do not override.

For example this:

.. code-block:: cylc

[scheduling]
[[graph]]
R1 = a => b
R1 = c => d

Is equivalent to this:

.. code-block:: cylc

[scheduling]
[[graph]]
R1 = """
a => b
c => d
"""

See :ref:`GraphTypes` for more on recurrence expressions,
and how multiple graphs combine.

The value should be a dependency graph the given recurrence.
Syntax examples follow; see also :ref:`User Guide Scheduling`
Expand Down