job runners: document handler interface

Author: oliver-sanders

src/plugins/index.rst

@@ -11,6 +11,7 @@ The following are "core" plugins maintained by the Cylc team:
    cylc-rose
    main-loop/index
    install/index
+   job-runners/index
 
 .. warning::
 

src/plugins/job-runners/index.rst

@@ -0,0 +1,7 @@
+.. _CustomJobSubmissionMethods:
+
+Custom Job Submission Methods
+-----------------------------
+
+.. autoclass:: cylc.flow.job_runner_handlers.documentation.ExampleHandler
+   :members:

src/user-guide/task-implementation/job-submission.rst

@@ -302,78 +302,3 @@ If you specify an :cylc:conf:`[events]execution timeout` and an
 ignored.
 
 .. cylc-scope::
-
-
-.. _CustomJobSubmissionMethods:
-
-Custom Job Submission Methods
------------------------------
-
-Defining a new job runner handler requires a little Python programming. Use
-the built-in handlers (e.g. :py:mod:`cylc.flow.job_runner_handlers.background`)
-as examples.
-
-
-An Example
-^^^^^^^^^^
-
-The following ``qsub.py`` module overrides the built-in *pbs*
-job runner handler to change the directive prefix from ``#PBS`` to
-``#QSUB``:
-
-.. TODO - double check that this still works, it's been a while
-
-.. code-block:: python
-
-   #!/usr/bin/env python3
-
-   from cylc.flow.job_runner_handlers.pbs import PBSHandler
-
-   class QSUBHandler(PBSHandler):
-       DIRECTIVE_PREFIX = "#QSUB "
-
-   JOB_RUNNER_HANDLER = QSUBHandler()
-
-If this is in the Python search path (see
-:ref:`Where To Put Job Runner Handler Modules` below) you can use it by
-name in your global configuration:
-
-.. code-block:: cylc
-
-   [platforms]
-       [[my_platform]]
-           hosts = myhostA, myhostB
-           job runner = qsub  # <---!
-
-Then in your ``flow.cylc`` file you can use this platform:
-
-.. code-block:: cylc
-
-   [scheduling]
-       [[graph]]
-           R1 = "a"
-   [runtime]
-       [[root]]
-           execution time limit = PT1M
-           platform = my_platform
-           [[[directives]]]
-               -l nodes = 1
-               -q = long
-               -V =
-
-Note, this workflow will fail at run time because we only changed the
-directive format, and PBS does not accept ``#QSUB`` directives in
-reality.
-
-
-.. _Where To Put Job Runner Handler Modules:
-
-Where To Put Job Runner Handler Modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Custom job runner handlers must be installed on workflow and job
-hosts in one of these locations:
-
-- under ``WORKFLOW-RUN-DIR/lib/python/``
-- under ``CYLC-PATH/cylc/flow/job_runner_handlers/``
-- or anywhere in ``$PYTHONPATH``