Cylc Message Help Contains two patterns of use

[wxtim]

Closes #5883

A single script might have multiple different valid arguments.

for example cylc message can be either

cylc message -- [WORKFLOW JOB [[SEVERITY:]MESSAGE ...]]] __or__
cylc message --	[[SEVERITY:]MESSAGE ...]]]

This PR fixes the Cylc message docs.

• Refactored part of the init method of CylcOptionParser. into a method for ease of testing.
• Added unit tests to get complete coverage of new method.

Note

The reason for this behaviour is given further down in the doc:

For backward compatibility, if number of arguments is less than or equal to 2,
the command assumes the classic interface, where all arguments are messages.
Otherwise, the first 2 arguments are assumed to be workflow ID and job
identifier.

Check List

• I have read CONTRIBUTING.md and added my name as a Code Contributor.
• Contains logically grouped changes (else tidy your branch by rebase).
• Does not contain off-topic changes (use other PRs for other changes).
• Applied any dependency changes to both setup.cfg (and conda-environment.yml if present).
• Tests are included (or explain why tests are not needed).
• This is effectively a documentation change and doesn't need logging in CHANGES.md or in the docs.
• If this is a bug fix, PR should be raised against the relevant ?.?.x branch.

[oliver-sanders]

Close, but the broken use case is still covered by the first usage, I think this does it:

diff --git a/cylc/flow/scripts/message.py b/cylc/flow/scripts/message.py
index 061d842475..b12f0e180f 100755
--- a/cylc/flow/scripts/message.py
+++ b/cylc/flow/scripts/message.py
@@ -109,8 +109,9 @@ def get_option_parser() -> COP:
         argdoc=[
             WORKFLOW_ID_ARG_DOC,
             ('JOB', 'Job ID - CYCLE/TASK_NAME/SUBMIT_NUM'),
+            ('[SEVERITY:]MESSAGE', 'Messages'),
             COP.optional(
-                ('[SEVERITY:]MESSAGE ...', 'Messages')
+                ('[SEVERITY:]MESSAGE', 'Messages')
             ),
             COP.LINEBREAK,
             COP.optional(('[SEVERITY:]MESSAGE ...', 'Messages')),

[oliver-sanders]

Whilst working with this branch checked out (as of last review) I got traceback for cylc tui <workflow>/<run1>.

[MetRonnie]

Is this test really worthwhile? Might end up as a maintenance drag

[wxtim]

I semi agree. On the other hand, it's easy enough to regenerate the files. I wonder if it might be worth just testing

• cylc message
• cylc broadcast
• cylc tui

Which demonstrate both patterns in the code I've changed in this PR, with the benefit of adding a double check on the two scripts which we least want to drift. I added TUI to the list, because it seems to be an outlier. This test would have caught the errors in my PR.

Do you think that this is reasonable @MetRonnie ?

[MetRonnie]

Might be worth it for cylc message and cylc broadcast as these have to be stable for task scripts. Not sure why it would be worth it for TUI

[wxtim]

Seems a little non-standard - it broke the original PR>

[oliver-sanders]

I don't get the point of this test?

All it's doing is checking whether any of the help text has changed?

It's not actually checking that the interfaces are documented correctly.

[wxtim]

The point is to check whether changes to the option parser have caused a change in the help text: My original changes caused unwanted changes - like the change to TUI.

Happy enough to remove if you really feel it's total overkill

[oliver-sanders]

You might want to have a quick skim over cylc message --help bearing in mind #5883...

[wxtim]

You might want to have a quick skim over cylc message --help bearing in mind #5883...

I'm not sure what your point was here. As far as I can see the behaviour makes sense and is correct but the docs are wrong. What behaviour are you unhappy with?

The behaviour described in #5883 looks exactly as I'd expect from a careful reading of --help.

@oliver-sanders - I'm not sure I remember what your objection to the way the app actually works was...