Merge branch 'master' into TestConfigVersion

docs/advanced.rst

@@ -9,6 +9,8 @@ give you a better idea of what it's capable of.
 Mode Configs
 ------------
 
+*Full Docs:* :ref:`tests.format.mode`
+
 In addition to host config files, you can provide mode config files that
 you can apply to any test when you run it. They have the same format as
 the host configs, but multiple can be provided per test.
@@ -22,9 +24,9 @@ set of slurm vars:
         account: tester
         partition: post-dst
 
-::
+.. code-block:: bash
 
-    pav run -m tester -f post_dst_tests.txt
+    $ pav run -m tester -f post_dst_tests.txt
 
 Advanced Test Configs
 ---------------------
@@ -36,6 +38,8 @@ variables.
 Variables
 ~~~~~~~~~
 
+*Full Docs:* :ref:`tests.variables`
+
 Test configs can contain *expressions* within their config values that
 reference and manipulate variables.
 
@@ -63,8 +67,13 @@ contain numbers, dashes and underscores.
           - "sleep {{var.sleep_time}}"
           - 'echo "Slept {{sleep_time}} seconds on node {{sched.node_num}}."'
 
-Variable References
-^^^^^^^^^^^^^^^^^^^
+Expressions
+^^^^^^^^^^^
+
+*Full Docs:* :ref:`tests.variables`
+
+Expressions allow you to access and manipulate variable values and insert them
+into Pavilion configuration strings.
 
 -  Use double curly brackets ``{{var.myvar}}``.
 -  Variable category is optional. ``{{myvar}}`` is fine.
@@ -73,8 +82,8 @@ Variable References
    you need to make the reference explicit.
 -  You'll also see ``{{myvar.2}}`` list references, ``{{myvar.foo}}``
    attribute references, and the combination of the two
-   ``{{myvar.1.bar}}``. See the full
-   `variable documentation <tests/variables.html>`__ for more info.
+   ``{{myvar.1.bar}}``.
+-  These can also contain math and function calls: ``{{ foo + 1 / bar }}``
 
 Listing Variables
 ^^^^^^^^^^^^^^^^^
@@ -115,19 +124,14 @@ in those sections. Namely, this includes the ``build`` and various
 scheduler config sections, as well as root level config values. Pavilion
 will tell you when you make this mistake.
 
-More Info
-^^^^^^^^^
-
-Variables are a powerful feature of pavilion, and the above just
-scratches the surface. See the `variables <tests/variables.html>`__
-section of the docs for detailed information.
-
 Expressions
 ~~~~~~~~~~~
 
+*Full Docs:* :ref:`tests.values.expressions`
+
 The double curly brace sections that can contain variables are really fully
-capable *expressions*, and can contain math operations and function calls. The
-syntax is Python-like and most operations work identically.
+capable :ref:`tests.values.expressions`, and can contain math operations and
+function calls.
 Functions are provided via plugins.
 
 .. code-block:: yaml
@@ -140,44 +144,33 @@ Functions are provided via plugins.
         cmds:
           - "sleep {{ max([var.sleep_time/4, 1, sleep_time + 1]) }}"
 
-See
 
 Inheritance
 ~~~~~~~~~~~
 
+*Full Docs:* :ref:`tests.format.inheritance`
+
 Tests within a single test suite file can inherit from each other.
 
 .. code-block:: yaml
 
-    super_magic:
-        summary: Run all standard super_magic tests.
-        scheduler: slurm
-        build:
-          modules:
-            - gcc
-            - openmpi
-          cmds:
-            - mpicc -o super_magic super_magic.c
+    test_a:
+        variables:
+            key1: "apple"
+            key2: "pear"
 
         run:
-          modules:
-            - gcc
-            - openmpi
-          cmds:
-            - echo "Running supermagic"
-            - srun ./supermagic -a
+            cmds: 'echo "{{key1}} {{key2}}"'
 
-        results:
-          ... # Various result parser configurations.
+    test_b:
+        inherits_from: test_a
+
+        variables:
+            key2: "banana"
+
+The first test, 'test_a', would echo "apple pear", while the second would
+echo "apple banana".
 
-    # This gets all the attributes of supermagic, but overwrites the summary
-    # and the test commands.
-    super_magic-fs:
-        summary: Run all standard super_magic tests, and the write test too.
-        inherits_from: super_magic
-        run:
-          cmds:
-            - srun ./supermagic -a -w /mnt/projects/myproject/
 
 Rules of Inheritance
 ^^^^^^^^^^^^^^^^^^^^
@@ -232,6 +225,8 @@ for more info.
 Skip Conditions
 ~~~~~~~~~~~~~~~
 
+*Full Docs:* :ref:`tests.skip_conditions`
+
 The ``only_if`` and ``not_if`` sections of the test config allow users
 to specify the conditions under which a test should run. Tests are 'SKIPPED'
 unless each of their ``only_if`` conditions (and none if their ``not_if``
@@ -252,10 +247,6 @@ value of the Pavilion variable might match to.
             cmds:
                 - 'echo "Helloworld"'
 
-See
-`Skip Conditions <tests/conditionals.html>`__
-for additional information.
-
 Environment
 -----------
 
@@ -265,8 +256,14 @@ environment (or lmod) modules.
 Environment Variables
 ~~~~~~~~~~~~~~~~~~~~~
 
-You can set/unset environment variables in your test configs, and use
-them in your scripts.
+*Full Docs:* :ref:`tests.env.variables`
+
+You can set environment variables in your test scripts using the
+'env' section under both 'run' and 'build'. This will cause the variables to
+be exported within the generated run or build script, where they can be used
+by commands run as part of that script. Note that environment variables are
+**only** usable in the *cmds* and *env* sections, as these are written
+directly into the build and run scripts.
 
 .. code-block:: yaml
 
@@ -277,12 +274,28 @@ them in your scripts.
             PYTHONPATH:
             # Use a different python home
             PYTHONHOME: /home/mario/python_root/
+            # Specify a python version
+            PY_VERS: 3
           cmds:
-            - 'python${PY_VERS} -c "print(\"hello world\")"'
+            - python${PY_VERS} -c "print('hello world')"
+
+This will result in a run script that looks like:
+
+.. code-block:: bash
+
+    #!/bin/bash
+
+    unset PYTHONPATH
+    export PYTHONHOME=/home/mario/python_root
+    export PY_VERS=3
+
+    python${PY_VERS} -c "print ('hello world')"
 
 Modules
 ~~~~~~~
 
+*Full Docs:* :ref:`tests.env.modules`
+
 You can have pavilion load module files automatically for each test or
 build. This assumes the modules (and module build combinations) are
 available on your system. If the test can't load a module, the test will
@@ -329,8 +342,8 @@ Module Wrappers
 
 When tell pavilion to load/remove/swap modules, the code to do this is
 added to the test or build script automatically using
-`module wrapper <plugins/module_wrappers.html>`__
-plugins. The default module wrapper performs the module command, and
+:ref:`plugins.module_wrappers`.
+The default module wrapper performs the module command, and
 then verifies that the module is actually loaded.
 
 More complicated setups are possible by adding additional plugins
@@ -403,7 +416,7 @@ scheduler, but don't configure one. It's time to rectify that.
             # that conforms to the rest of the slurm settings.
             - {sched.test_cmd} ./supermagic -a
 
-`Schedulers are plugins <plugins/schedulers.html>`__ in Pavilion, and are
+Schedulers are plugins in Pavilion, and are
 fairly loosely defined. They must at least do the following:
 
 * Provide a scheduler variable set for use in configs (the set may be empty).

docs/basics.rst

@@ -7,7 +7,7 @@ Getting Started
 Setup
 ~~~~~
 
-See the `install docs <install.html>`__ if you need to install Pavilion*
+See the :ref:`install` if you need to install Pavilion*
 
 Add the PAV bin directory to your Path.
 
@@ -29,8 +29,8 @@ Configure Tests
 Pavilion doesn't come with any tests itself; it's just a system for
 running them on HPC clusters. Each test needs a configuration script,
 and most will need some source files. Both of these will live in one of
-your `config directories <config.html#config-directories>`__ under the
-``tests/`` and ``test_src/`` sub-directories.
+your :ref:`config.config_dirs` under the ``tests/`` and ``test_src/``
+sub-directories.
 
 Test configs tell pavilion what environment it needs to build and run
 your test, the commands to run it, how to schedule it on a cluster, and
@@ -72,7 +72,7 @@ config directory.
 This config is used to override the Pavilion defaults for values in
 every test config run on that system. You can use these to set default
 values for things like the max nodes per job in a given scheduler,
-or setting useful `variables <tests/variables.html>`__ for that system. The
+or setting useful :ref:`tests.variables` for that system. The
 format is the same as a test config file, except with only one test and
 without the name for that test.
 
@@ -85,8 +85,8 @@ without the name for that test.
 The above host config would set the default scheduler to 'slurm' for
 tests kicked off on a host with a hostname of ``my_host``. Pavilion uses
 the contents of the ``sys_name`` test config variable to determine the
-current host, which is provided via a built-in `system variable
-plugin <plugins/sys_vars.html>`__. This behaviour can be overridden by
+current host, which is provided via a built-in
+:ref:`plugins.sys_vars`. This behaviour can be overridden by
 providing your own sys\_var plugin, which is especially useful on
 clusters with multiple front-ends.
 
@@ -171,7 +171,7 @@ From the above, you may have noticed that each test gets a series id
 like ``s24`` and a test id like ``41``. You can use these id's to
 reference tests or suites of tests to get their status, results, and
 logs through the pavilion interface. The ID's are unique for a given
-Pavilion `working\_directory <config.html#working-dir>`__, but they will
+Pavilion :ref:`config.working_dir` but they will
 get reused as old tests are cleaned up.
 
 Test Results
@@ -203,7 +203,8 @@ When the test run was created - started - When the test actually started
 - finished - When the test run completed
 
 By default, a test passes if it's last command returns 0. You can
-override this behaviour by using `result parsers <tests/results.html>`__.
+override this behaviour by using result parsers and evaluations
+(:ref:`tests.results`).
 You can also use result parsers to add additional, arbitrary values to
 the test results.
 

docs/config.rst

@@ -1,28 +1,34 @@
+.. _config:
+
 Configuring Pavilion
 ====================
 
 Pavilion is driven largely by configurations. This documentation page covers
 the ``pavilion.yaml`` file, which sets global pavilion settings.
 
-See `Test Configs <tests/format.html>`__,
-`Host Configs <tests/format.html#host-configs>`__,
-`Mode Configs <tests/format.html#mode-configs>`__, and
-`Plugins <plugins/basics.html>`__ for information on the other types of
+See :ref:`tests.format` for information on the other types of
 pavilion configuration.
 
 .. contents::
 
+.. _config.config_dirs:
+
 Config Directories
 ------------------
 
-Pavilion looks for configs in the following hierarchy by default, and
-uses the first one it finds.
+Pavilion looks its main ``pavilion.yaml`` config in the following hierarchy
+and uses the first one it finds.
 
--  The current directory
--  The user's home directory
+-  The user's `~/.pavilion` directory.
 -  The directory given via the ``PAV_CONFIG_DIR`` environment variable.
 -  The Pavilion lib directory **(don't put configs here)**
 
+The pavilion.yaml file can configure additional locations to look for test,
+mode, and host configs, as well as plugins using the ``config_dirs`` option.
+The ``~/.pavilion`` directory is only searched for ``pavilion.yaml`` by
+default, but searches for other configs there can be turned on in ``pavilion
+.yaml``
+
 Each config directory can (optionally) have any of the sub-directories
 shown here.
 
@@ -31,29 +37,25 @@ shown here.
 
    Config Directory Layout
 
-Pavilion.yaml
--------------
-
-Pavilion looks for a ``pavilion.yaml`` in the default config hierarchy,
-and uses the first one it finds.
-
-It's ok to run pavilion without a config; the defaults should be good
-enough in many cases.
+It's ok to run pavilion without a ``pavilion.yaml``; the defaults should
+be good enough in many cases.
 
 Generating a pavilion.yaml template
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Pavilion can print template files, with documentation, for all of it's
 config files. In this case, use the command ``pav show config --template``.
-Since this file is self documenting, refer to it for more information about
-each of the configuration settings.
+Since this file is self documenting, refer to
+it for more information about each of the configuration settings.
 
 Setting You Should Set
 ~~~~~~~~~~~~~~~~~~~~~~
 
 While everything has a workable default, you'll probably want to set the
 following.
 
+.. _config.working_dir:
+
 working_dir
 ^^^^^^^^^^^
 

docs/index.rst

@@ -30,6 +30,7 @@ Project goals:
    install.rst
    advanced.rst
    config.rst
+   test_run_lifecycle.rst
    tests/index.rst
    plugins/index.rst
 

docs/install.rst

@@ -1,5 +1,6 @@
 
 .. _installing-pavilion:
+.. _install:
 
 Installing Pavilion
 ===================
@@ -58,7 +59,7 @@ We recommend the following directory structure for Pavilion.
 
 - ``<root>/pavilion/src`` - Clone/install pavilion here.
 - ``<root>/pavilion/config`` - Your pavilion configuration files. See
-  '`configuring pavilion <config.html>`__'.
+  :ref:`config`.
 - ``<root>/pavilion/working_dir`` - Where test runs and builds will be written.
 
 The ``<root>/pavilion/config`` directory will contain all of your site
@@ -170,8 +171,7 @@ that supports multiple compilers and conflicting builds of libraries.
 
 It is assumed that the module environment is set up before you run Pavilion. If
 you need to set up this environment separately on allocations, use the
-'env_setup' option in the
-`general Pavilion configuration <config.html>`__ to add the commands
+'env_setup' option in the :ref:`config` to add the commands
 to do so.