Xtriggers: Doc Fixes #686

wxtim · 2024-02-01T15:48:29Z

Companion to cylc/cylc-flow#5955.
Closes #106

Also contains some misc fixes.

Have make clean remove src/plugins/xtriggers.
Make the xtrigger plugins document the eponymous method rather than the module: i.e. xtrigger.xtrigger.__doc__ not xtrigger.__doc__, which has almost no information.
Note the existence of validation functions in src/user-guide/writing_workflows/external_triggers.
Give an example of a simple xtrigger validation function.

Requirements check-list

I have read CONTRIBUTING.md and added my name as a Code Contributor.

- Make the extrigger plugins document the eponymous method rather than the module. - Note the existence of validation functions in src/user-guide/writing_workflows/external_triggers. - Give an example of a simple xtrigger validation function.

MetRonnie

After my suggestions to cylc/cylc-flow#5955 are resolved:

src/user-guide/writing-workflows/external-triggers.rst

MetRonnie

wxtim#6

* Fix xtrigger entry point example * Update xtrigger plugins docs

- Added "secs" and "subprocess" to dictionary.

MetRonnie · 2024-02-26T14:32:26Z

Kicking tests

MetRonnie · 2024-02-26T14:46:27Z

Ugh, still failing because apparently we run doctests here?

oliver-sanders · 2024-02-26T16:59:10Z

src/dictionaries/words

@@ -146,6 +148,7 @@ ret
 retrigger
 retriggered
 retriggering
+rmtree


Manually adding every argument name to the dictionary is going to get painful.

Any ideas on excluding function signatures and argument lists from spellcheck?

@oliver-sanders I've worked up a proof of concept at https://github.com/cylc/cylc-doc/compare/master...wxtim:cylc-doc:custom_filter_for_Cylc_Words?expand=1 - but I'm not terribly happy with the methods at the top of cylc.doc.filters which are scraping the Cylc code.

MetRonnie · 2024-03-22T17:55:22Z

@oliver-sanders Even if I add the required xtrigger imports in a .. testsetup:: block, the Sphinx doctest does not seem to obey the patching done in the xrandom doctest: https://github.com/cylc/cylc-flow/blob/2b2fc7721f4bc0c05c7384170ddc82278aad5875/cylc/flow/xtriggers/xrandom.py#L69-L75 so the doctest is flaky

There is apparently no way to exclude cylc/flow/ code from Sphinx doctest either.

So I think we will either have to remove the doctest extension from conf.py or remove the examples in the xrandom docstring?

oliver-sanders · 2024-03-26T16:10:47Z

I don't think testsetup will help here?

Have you tried replacing __name__ with its expected value?

MetRonnie · 2024-04-23T11:53:16Z

Would be good to get this in. Pending:

Small merge conflict
Decision on whether to remove the doctest extension from conf.py or remove the examples in the xrandom docstring

oliver-sanders · 2024-04-23T12:10:50Z

Fine, check that:

There aren't any doctests in the cylc-doc codebase.
Doctests are definitely run as part of regular tests in all the upstream repos.

If so, we can remove the doctest build from cylc-doc. This build predated our use of pytest which we now configure to run doctests on the source repos.

MetRonnie · 2024-04-23T12:36:00Z

Checked; doctests (on master) currently only test cylc/flow/jinja/filters which is definitely already doctested in cylc-flow

PR opened at wxtim#8

Xtrigger docs: remove doctest

src/user-guide/writing-workflows/external-triggers.rst

Co-authored-by: Oliver Sanders <[email protected]>

src/user-guide/writing-workflows/external-triggers.rst

oliver-sanders · 2024-04-24T16:16:12Z

Recommendation: wxtim#9

xtiggers: flesh out validation

…gger It has no effect as `wall_clock` is specially implemented

MetRonnie · 2024-04-25T12:58:31Z

Hopefully the last recommendation: wxtim#10

Xtrig

oliver-sanders · 2024-04-25T15:13:46Z

src/user-guide/writing-workflows/external-triggers.rst

+   :members: xrandom, validate
+   :member-order: bysource


It is not helpful to provide API reference for this internal interface as it has no valid external application.

Suggested change

:members: xrandom, validate

:member-order: bysource

:members: xrandom

True but it does provide a link to the source so it is not useless IMO

cylc/cylc-flow#6084

hjoliver

Looks good 👍

wxtim requested a review from MetRonnie February 1, 2024 15:48

wxtim self-assigned this Feb 1, 2024

wxtim added this to the 8.3.0 milestone Feb 1, 2024

wxtim mentioned this pull request Feb 1, 2024

Xtrig arg validate cylc/cylc-flow#5955

Merged

8 tasks

spelling fixes

5ecefd3

wxtim force-pushed the xtrig-arg-validate branch from 2cc987c to 5ecefd3 Compare February 1, 2024 16:44

MetRonnie reviewed Feb 5, 2024

View reviewed changes

MetRonnie requested changes Feb 15, 2024

View reviewed changes

Fix xtrigger entry point example and improve docs (#6)

8c84e9b

* Fix xtrigger entry point example * Update xtrigger plugins docs

MetRonnie mentioned this pull request Feb 20, 2024

Autodoc built-in xtrigger functions #673

Closed

1 task

- Added a reference to built-in "Toy" xtriggers.

3a5eabd

- Added "secs" and "subprocess" to dictionary.

wxtim requested a review from MetRonnie February 22, 2024 08:59

This comment was marked as resolved.

Sign in to view

wxtim marked this pull request as draft February 23, 2024 11:46

wxtim marked this pull request as ready for review February 23, 2024 13:57

This comment was marked as resolved.

Sign in to view

Actions: pip list on build failure for debugging (#7)

c6bcf10

This comment was marked as resolved.

Sign in to view

MetRonnie mentioned this pull request Feb 26, 2024

Fix sphinx autodoc warning cylc/cylc-uiserver#560

Merged

7 tasks

MetRonnie closed this Feb 26, 2024

MetRonnie reopened this Feb 26, 2024

MetRonnie mentioned this pull request Feb 26, 2024

parentless sequential xtrigger spawning cylc/cylc-flow#5738

Merged

7 tasks

oliver-sanders reviewed Feb 26, 2024

View reviewed changes

MetRonnie added 2 commits April 23, 2024 13:37

Merge branch 'master' into pr-686

2fa2f87

Remove doctest

c1735ff

MetRonnie mentioned this pull request Apr 23, 2024

Xtrigger docs: remove doctest wxtim/cylc-doc#8

Merged

1 task

Merge pull request #8 from MetRonnie/pr-686

6e66136

Xtrigger docs: remove doctest

MetRonnie approved these changes Apr 23, 2024

View reviewed changes

oliver-sanders reviewed Apr 24, 2024

View reviewed changes

src/user-guide/writing-workflows/external-triggers.rst Outdated Show resolved Hide resolved

oliver-sanders reviewed Apr 24, 2024

View reviewed changes

src/user-guide/writing-workflows/external-triggers.rst Outdated Show resolved Hide resolved

oliver-sanders mentioned this pull request Apr 24, 2024

xtriggers: docstring formatting fixes cylc/cylc-flow#6083

Merged

8 tasks

wxtim and others added 2 commits April 24, 2024 13:49

Update src/user-guide/writing-workflows/external-triggers.rst

ae1013b

Co-authored-by: Oliver Sanders <[email protected]>

remove surplus material

bfc92d1

oliver-sanders reviewed Apr 24, 2024

View reviewed changes

src/user-guide/writing-workflows/external-triggers.rst Outdated Show resolved Hide resolved

wxtim requested a review from oliver-sanders April 24, 2024 15:37

wxtim and others added 2 commits April 24, 2024 17:01

make code refs work

f445bbf

xtiggers: flesh out validation

9035b3a

wxtim added 2 commits April 25, 2024 08:10

Merge branch 'xtrig-arg-validate' into xtrigger-stuff

85e0ec1

Merge pull request #9 from oliver-sanders/xtrigger-stuff

33a6bd0

xtiggers: flesh out validation

oliver-sanders approved these changes Apr 25, 2024

View reviewed changes

MetRonnie added 2 commits April 25, 2024 13:56

Remove outdated references to :interval suffix on wall_clock xtri…

c4a6056

…gger It has no effect as `wall_clock` is specially implemented

xrandom: autodoc validate function & remove repeated content

95fb337

MetRonnie mentioned this pull request Apr 25, 2024

Xtrig wxtim/cylc-doc#10

Merged

Merge pull request #10 from MetRonnie/xtrig

d18b130

Xtrig

oliver-sanders self-requested a review April 25, 2024 15:13

oliver-sanders reviewed Apr 25, 2024

View reviewed changes

hjoliver approved these changes Apr 25, 2024

View reviewed changes

MetRonnie merged commit a5bf3d0 into cylc:master Apr 26, 2024
1 check passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Xtriggers: Doc Fixes #686

Xtriggers: Doc Fixes #686

wxtim commented Feb 1, 2024 •

edited by MetRonnie

Loading

MetRonnie left a comment

MetRonnie left a comment

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

MetRonnie commented Feb 26, 2024

MetRonnie commented Feb 26, 2024

oliver-sanders Feb 26, 2024 •

edited

Loading

wxtim Mar 5, 2024

MetRonnie commented Mar 22, 2024 •

edited

Loading

oliver-sanders commented Mar 26, 2024

MetRonnie commented Apr 23, 2024 •

edited

Loading

oliver-sanders commented Apr 23, 2024 •

edited by MetRonnie

Loading

MetRonnie commented Apr 23, 2024 •

edited

Loading

oliver-sanders commented Apr 24, 2024

MetRonnie commented Apr 25, 2024

oliver-sanders Apr 25, 2024 •

edited

Loading

MetRonnie Apr 25, 2024

MetRonnie Apr 25, 2024

hjoliver left a comment

	:members: xrandom, validate
	:member-order: bysource
	:members: xrandom

Xtriggers: Doc Fixes #686

Xtriggers: Doc Fixes #686

Conversation

wxtim commented Feb 1, 2024 • edited by MetRonnie Loading

MetRonnie left a comment

Choose a reason for hiding this comment

MetRonnie left a comment

Choose a reason for hiding this comment

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

MetRonnie commented Feb 26, 2024

MetRonnie commented Feb 26, 2024

oliver-sanders Feb 26, 2024 • edited Loading

Choose a reason for hiding this comment

wxtim Mar 5, 2024

Choose a reason for hiding this comment

MetRonnie commented Mar 22, 2024 • edited Loading

oliver-sanders commented Mar 26, 2024

MetRonnie commented Apr 23, 2024 • edited Loading

oliver-sanders commented Apr 23, 2024 • edited by MetRonnie Loading

MetRonnie commented Apr 23, 2024 • edited Loading

oliver-sanders commented Apr 24, 2024

MetRonnie commented Apr 25, 2024

oliver-sanders Apr 25, 2024 • edited Loading

Choose a reason for hiding this comment

MetRonnie Apr 25, 2024

Choose a reason for hiding this comment

MetRonnie Apr 25, 2024

Choose a reason for hiding this comment

hjoliver left a comment

Choose a reason for hiding this comment

wxtim commented Feb 1, 2024 •

edited by MetRonnie

Loading

oliver-sanders Feb 26, 2024 •

edited

Loading

MetRonnie commented Mar 22, 2024 •

edited

Loading

MetRonnie commented Apr 23, 2024 •

edited

Loading

oliver-sanders commented Apr 23, 2024 •

edited by MetRonnie

Loading

MetRonnie commented Apr 23, 2024 •

edited

Loading

oliver-sanders Apr 25, 2024 •

edited

Loading