Revert "job runners: document handler interface"

Author: wxtim

src/conf.py

@@ -122,12 +122,6 @@
     )
 }
 
-nitpick_ignore = [
-    # This class appears in documented type-hints but is not documented in the
-    # Python docs so fails build.
-    ('py:class', 're.Pattern')
-]
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # exclude_patterns = ['_build']

src/dictionaries/words

@@ -1,7 +1,5 @@
-Popen
 app
 apps
-arg
 args
 auth
 authenticator
@@ -133,7 +131,6 @@ requeued
 resends
 resolvers
 resubmission
-ret
 retrigger
 retriggered
 retriggering
@@ -155,7 +152,6 @@ ssh
 st
 startup
 stderr
-stdin
 stdout
 str
 strftime

src/plugins/index.rst

@@ -11,7 +11,6 @@ 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

@@ -302,3 +302,78 @@ 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``