add reference material for submit.yml.erb back (#891)

Add reference material for submit.yml.erb back.

source/how-tos/app-development/interactive/form.rst

@@ -132,18 +132,24 @@ part of the app developer can look like:
 
 The most commonly used predefined attributes are given as:
 
+.. _bc_account:
+
 bc_account
   This adds a ``text_field`` to the HTML form that will be used as the charged
   account for the submitted job.
 
   This attribute gets directly set on `OodCore::Job::Script#accounting_id`_.
 
+.. _bc_queue:
+
 bc_queue
   This adds a ``text_field`` to the HTML form that will supply the name of the
   queue that the batch job is submitted to.
 
   This attribute gets directly set on `OodCore::Job::Script#queue_name`_.
 
+.. _bc_num_hours:
+
 bc_num_hours
   This adds a ``number_field`` to the HTML form that describes the maximum
   amount of hours the submitted batch job may run.
@@ -167,6 +173,8 @@ bc_num_slots
      :ref:`interactive-development-form-customizing-attributes`) to work at
      your center.
 
+.. _bc_email_on_started:
+
 bc_email_on_started
   This adds a ``check_box`` to the HTML form that determines whether the user
   should be notified by email when the batch job starts.
@@ -223,12 +231,15 @@ auto_modules_<MODULE>
     referenced in the ``script.sh.erb`` as ``<%= auto_modules_netcdf_serial %>``
     replacing any hyphens (``-``) with underscores ``_``.
 
+.. _auto_groups:
 
 auto_groups
   This will automatically generate a ``select`` widget populated with a list of the Unix
   groups the user is currently in. Administrators can configure :ref:`filter for autogroups <auto_groups_filter>`
   to limit the groups shown.
 
+.. _auto_queues:
+
 auto_queues
   This will generate a ``select`` widget list of all the queues available to the user.
   These queues will be cluster if you have :ref:`dynamic options <dynamic-bc-apps>`
@@ -238,6 +249,8 @@ auto_queues
   .. warning::
     We only have support for Slurm queues (partitions) at this time.
 
+.. _auto_accounts:
+
 auto_accounts
   This will generate a ``select`` widget list of all the accounts available to the user.
 

source/how-tos/app-development/interactive/global-submit.inc

@@ -0,0 +1,18 @@
+Setting Batch Connect Options Globally
+--------------------------------------
+
+All of these configuration items can also be applied globally to the entire cluster
+in the cluster definition files under ``/etc/ood/config/clusters.d/``. If set globally,
+the option is applied to all applications in that cluster.
+
+Here's an example of how to set the ``header`` configuration for both vnc and basic
+templates.
+
+  .. code-block:: yaml
+
+    v2:
+      batch_connect:
+        basic:
+          header: "#!/bin/bash"
+        vnc:
+          header: "#!/bin/bash"

source/how-tos/app-development/interactive/submit.rst

@@ -7,6 +7,12 @@ The configuration file ``submit.yml.erb`` controls the content of the batch
 script as well as the submission arguments used when submitting the batch job.
 It is located in the root of the application directory.
 
+.. tip::
+  This page is an introduction to the ``submit.yml.erb``, it's contents
+  and it's use.
+
+  Reference documentation holds :ref:`all configuration items for submit.yml.erb <submit-yml-erb>`.
+
 Assuming we already have a sandbox Interactive App deployed under::
 
   ${HOME}/ondemand/dev/my_app
@@ -28,8 +34,8 @@ The three possible configuration options that can be used in the
 
 .. describe:: batch_connect (Hash)
 
-   the configuration describing the batch script content (see
-   `OodCore::BatchConnect::Template`_ for valid configuration options)
+   The configuration describing the batch script content.
+   Reference documentation holds :ref:`all configuration items for submit.yml.erb <submit-yml-erb>`.
 
    Example
      Use the default basic web server template
@@ -43,8 +49,9 @@ The three possible configuration options that can be used in the
 
 .. describe:: script (Hash)
 
-   the configuration describing the job submission parameters for the batch
-   script (see `OodCore::Job::Script`_ for valid configuration options)
+   The configuration describing the job submission parameters for the batch
+   script. Reference documentation holds
+   :ref:`all configuration items for submit.yml.erb <submit-yml-erb>`.
 
    Example
      Set the job's charged account and queue
@@ -112,22 +119,20 @@ All batch scripts are generated from either the ``basic`` template or the
         batch_connect:
           template: "vnc"
 
-Aside from the above configuration option, a list of all possible configuration
-options for ``batch_connect`` can be found under the code documentation for
-`OodCore::BatchConnect::Template`_.
+Reference documentation holds :ref:`all configuration items for submit.yml.erb <submit-yml-erb>`.
 
 .. note::
 
    The configuration ``template: "vnc"`` comes with more ``batch_connect``
    configuration options which can be found under the code documentation for
-   `OodCore::BatchConnect::Templates::VNC`_.
+   :ref:`vnc-bc-options`.
 
 Configure Script
 ````````````````
 
 The ``script`` configuration option defines the batch job submission parameters
 (e.g., number of nodes, wall time, queue, ...). The list of all possible
-options can be found under the code documentation for `OodCore::Job::Script`_.
+options can be found under the code documentation for :ref:`submit-script-options`.
 
 It is recommended to refrain from using the ``native`` option to best keep your
 Interactive App as portable as possible. Although we understand this may not be
@@ -221,7 +226,7 @@ script it forks off into the background. This can be configured with:
 Specify Job Submission Parameters
 `````````````````````````````````
 
-Cherry-picking some possible options from `OodCore::Job::Script`_ gives a batch
+Cherry-picking some possible options from :ref:`submit-script-options` gives a batch
 job built from the basic web server template submitted with the following
 parameters:
 
@@ -299,27 +304,7 @@ the user supplied a non-blank value to the form attribute ``my_queue``.
 
 .. _global-bc-settings:
 
-Setting Batch Connect Options Globally
-``````````````````````````````````````
-
-All of these configuration items can also be applied globally to the entire cluster
-in the cluster definition files under ``/etc/ood/config/clusters.d/``. If set globally,
-the option is applied to all applications in that cluster.
-
-Here's an example of how to set the ``header`` configuration for both vnc and basic
-templates.
-
-  .. code-block:: yaml
-
-    v2:
-      batch_connect:
-        basic:
-          header: "#!/bin/bash"
-        vnc:
-          header: "#!/bin/bash"
+.. include:: global-submit.inc
 
 .. _eruby (embedded ruby): https://en.wikipedia.org/wiki/ERuby
-.. _`oodcore::batchconnect::template`: http://www.rubydoc.info/gems/ood_core/OodCore/BatchConnect/Template
-.. _`oodcore::batchconnect::templates::vnc`: http://www.rubydoc.info/gems/ood_core/OodCore/BatchConnect/Templates/VNC
-.. _`oodcore::job::script`: http://www.rubydoc.info/gems/ood_core/OodCore/Job/Script
 .. _ruby strings: https://ruby-doc.org/core-2.2.3/String.html

source/reference.rst

@@ -14,6 +14,7 @@ make up the Open OnDemand infrastructure.
    reference/files/ood-portal-yml
    reference/files/nginx-stage-yml
    reference/files/ondemand-d-ymls
+   reference/files/submit-yml-erb.rst
 
 .. toctree::
    :maxdepth: 1

source/reference/files/submit-yml-erb.rst

@@ -0,0 +1,36 @@
+.. _submit-yml-erb:
+
+submit.yml.erb
+==============
+
+This is the file that is submitted to a batch connect job. It is comprised
+of a ``script`` and a ``batch_connect`` attribute.  The ``batch_connect``
+attribute can either be a ``basic`` template if your app is already an
+http server or a ``vnc`` template if you need VNC capabilities.
+
+These are reference pages, you can see 
+:ref:`app-development-interactive-submit` for a broader overview.
+
+.. toctree::
+   :maxdepth: 2
+
+   submit-yml/basic-bc-options
+   submit-yml/vnc-bc-options
+   submit-yml/script
+
+Simple Example
+--------------
+
+  .. code-block:: yaml
+
+      # a simple script.yml.erb file
+
+      script:
+        native:
+          - "-n"
+          - "1"
+      batch_connect:
+        template: "basic"
+        header: "#!/bin/bash"
+
+.. include:: ../../how-tos/app-development/interactive/global-submit.inc