include a description of WORKFLOW_SHARE_DIR/bin and lib/python

Author: wxtim

src/user-guide/writing-workflows/configuration.rst

@@ -55,6 +55,10 @@ Other files and folders may be placed in the :term:`source directory` too:
 documentation, configuration files, etc. When the workflow is :ref:`installed
 <Installing-workflows>` these will be copied over to the :term:`run directory`.
 
+If your workflow needs to create or install scripts or executables at runtime
+and you don't want Cylc to delete them on re-installation, you can create
+equivalent directories in the :ref:`WorkflowShareDirectories`.
+
 
 .. _SyntaxHighlighting:
 

src/user-guide/writing-workflows/runtime.rst

@@ -306,6 +306,8 @@ exported to subshells:
                                    #   relative to the workflow work directory
 
 
+.. _WorkflowShareDirectories:
+
 Workflow Share Directories
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -317,6 +319,16 @@ output files are typically held in cycle point sub-directories of this.
 The top level share directory location can be changed, e.g. to a large data
 area, by global config settings under :cylc:conf:`global.cylc[install][symlink dirs]`.
 
+If your workflow creates or installs executables or python libraries
+as it is running, these can be placed in:
+
+* ``share/bin`` - for executables.
+* ``share/lib/python`` - for Python modules.
+
+These folders will be added to ``PATH`` and ``PYTHONPATH`` so they can be
+used by jobs in the same way as
+:ref:`top level "bin/" and "lib/python/" directories <WorkflowDefinitionDirectories>`.
+
 
 Task Work Directories
 ^^^^^^^^^^^^^^^^^^^^^