job runners: document handler interface

[oliver-sanders]

Sibling: https://github.com/cylc/cylc-flow/pull/5389

The documentation for the job runner handler interface is poor but I found a docstring in cylc-flow with valuable information which wasn't being auto-documented.

• Move existing documentation into a class for easier auto-documentation.
• Pull in a little content from cylc-doc and attempt to pad things out a little.
• Pull in lists of fields for job_conf and submit_opts obtained from the codebase.

I'm not taking the time for a full documentation re-write right now (no time) so this is mostly just what was already there reformatted and auto documented. The important thing is to expose this documentation as there are people trying to write handlers ATM.

@hjoliver if you get a chance to skim this that would be great.

[wxtim]

You'll want to add the following the dictionaries

• stdin
• arg (singular)
• Popen

You could choose to add ret to the dictionary, or change the variable ret_code in the example code to return_code.

[oliver-sanders]

What! The spellchecker is testing argument names and return types in autogenerated code reference!!!

[wxtim]

What! The spellchecker is testing argument names and return types in autogenerated code reference!!!

The spellchecker is remarkably unsophisticated, unfortunately.

[oliver-sanders]

Done.

We currently have a user waiting flying blind without the benefit of these docs so could do with getting this into the nightly builds quickly.

[wxtim]

Reverted - I missed the fact that this is still not building correctly. :(

[oliver-sanders]

Wait, hang on, @wxtim is this in or not?