Add SC16 tutorial to the Spack docs. (#2334)

13 files changed, 64 insertions, 17 deletions

diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst
index 65fb995d1e..ed2ff96ed0 100644
--- a/lib/spack/docs/index.rst
+++ b/lib/spack/docs/index.rst
@@ -61,11 +61,9 @@ or refer to the full manual below.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Step-by-step
+   :caption: Tutorial
 
-   basic_usage_tutorial
-   module_file_tutorial
-   package_tutorial
+   tutorial_sc16
 
 .. toctree::
    :maxdepth: 2
diff --git a/lib/spack/docs/tutorial/.gitattributes b/lib/spack/docs/tutorial/.gitattributes
new file mode 100644
index 0000000000..71905cea7d
--- /dev/null
+++ b/lib/spack/docs/tutorial/.gitattributes
@@ -0,0 +1 @@
+Spack-SC16-Tutorial.pdf filter=lfs diff=lfs merge=lfs -text
diff --git a/lib/spack/docs/tutorial/Spack-SC16-Tutorial.pdf b/lib/spack/docs/tutorial/Spack-SC16-Tutorial.pdf
new file mode 100644
index 0000000000..12dd4fe06f
--- /dev/null
+++ b/lib/spack/docs/tutorial/Spack-SC16-Tutorial.pdf
diff --git a/lib/spack/docs/packaging_tutorial/0.package.py b/lib/spack/docs/tutorial/examples/0.package.py
index ad6fd4d077..ad6fd4d077 100644
--- a/lib/spack/docs/packaging_tutorial/0.package.py
+++ b/lib/spack/docs/tutorial/examples/0.package.py
diff --git a/lib/spack/docs/packaging_tutorial/1.package.py b/lib/spack/docs/tutorial/examples/1.package.py
index afacf3bbe8..afacf3bbe8 100644
--- a/lib/spack/docs/packaging_tutorial/1.package.py
+++ b/lib/spack/docs/tutorial/examples/1.package.py
diff --git a/lib/spack/docs/packaging_tutorial/2.package.py b/lib/spack/docs/tutorial/examples/2.package.py
index f7000cd1b6..f7000cd1b6 100644
--- a/lib/spack/docs/packaging_tutorial/2.package.py
+++ b/lib/spack/docs/tutorial/examples/2.package.py
diff --git a/lib/spack/docs/packaging_tutorial/3.package.py b/lib/spack/docs/tutorial/examples/3.package.py
index 6e7e5e2f3c..6e7e5e2f3c 100644
--- a/lib/spack/docs/packaging_tutorial/3.package.py
+++ b/lib/spack/docs/tutorial/examples/3.package.py
diff --git a/lib/spack/docs/packaging_tutorial/4.package.py b/lib/spack/docs/tutorial/examples/4.package.py
index 3294b86e25..3294b86e25 100644
--- a/lib/spack/docs/packaging_tutorial/4.package.py
+++ b/lib/spack/docs/tutorial/examples/4.package.py
diff --git a/lib/spack/docs/tutorial/sc16-tutorial-slide-preview.png b/lib/spack/docs/tutorial/sc16-tutorial-slide-preview.png
new file mode 100644
index 0000000000..e7f9b2e323
--- /dev/null
+++ b/lib/spack/docs/tutorial/sc16-tutorial-slide-preview.png
diff --git a/lib/spack/docs/tutorial_sc16.rst b/lib/spack/docs/tutorial_sc16.rst
new file mode 100644
index 0000000000..e8cf3aeebe
--- /dev/null
+++ b/lib/spack/docs/tutorial_sc16.rst
@@ -0,0 +1,48 @@
+.. _spack-101:
+
+=============================
+Spack 101
+=============================
+
+This is a 3-hour introduction to Spack with lectures and live demos.  It
+was presented as a tutorial at `Supercomputing 2016
+<http://sc16.supercomputing.org>`_.  You can use these materials to teach
+a course on Spack at your own site, or you can just skip ahead and read
+the live demo scripts to see how Spack is used in practice.
+
+.. _sc16-slides:
+
+.. rubric:: Slides
+
+.. figure:: tutorial/sc16-tutorial-slide-preview.png
+   :target: _downloads/Spack-SC16-Tutorial.pdf
+   :height: 72px
+   :align: left
+   :alt: Slide Preview
+
+:download:`Download Slides <tutorial/Spack-SC16-Tutorial.pdf>`.
+
+**Full citation:** Todd Gamblin, Massimiliano Culpo, Gregory Becker, Matt
+Legendre, Greg Lee, Elizabeth Fischer, and Benedikt Hegner.
+`Managing HPC Software Complexity with Spack
+<http://sc16.supercomputing.org/presentation/?id=tut166&sess=sess209>`_.
+Tutorial presented at Supercomputing 2016. November 13, 2016, Salt Lake
+City, UT, USA.
+
+.. _sc16-live-demos:
+
+.. rubric:: Live Demos
+
+These scripts will take you step-by-step through basic Spack tasks.  They
+correspond to sections in the slides above.
+
+  1. :ref:`basics-tutorial`
+  2. :ref:`packaging-tutorial`
+  3. :ref:`modules-tutorial`
+
+Full contents:
+
+.. toctree::
+   tutorial_sc16_spack_basics
+   tutorial_sc16_packaging
+   tutorial_sc16_modules
diff --git a/lib/spack/docs/module_file_tutorial.rst b/lib/spack/docs/tutorial_sc16_modules.rst
index 83df756566..1e786674bb 100644
--- a/lib/spack/docs/module_file_tutorial.rst
+++ b/lib/spack/docs/tutorial_sc16_modules.rst
@@ -1,4 +1,4 @@
-.. _module_tutorial:
+.. _modules-tutorial:
 
 =============================
 Module Configuration Tutorial
diff --git a/lib/spack/docs/package_tutorial.rst b/lib/spack/docs/tutorial_sc16_packaging.rst
index e955780345..41c938327e 100644
--- a/lib/spack/docs/package_tutorial.rst
+++ b/lib/spack/docs/tutorial_sc16_packaging.rst
@@ -1,4 +1,4 @@
-.. _package_tutorial:
+.. _packaging-tutorial:
 
 =========================
 Package Creation Tutorial
@@ -37,7 +37,7 @@ A few things before we get started:
   editor you like.
 - We'll be writting Python code as part of this tutorial.  You can find
   successive versions of the Python code in
-  ``$SPACK_ROOT/lib/spack/docs/packaging_tutorial``.
+  ``$SPACK_ROOT/lib/spack/docs/tutorial/examples``.
 
 -------------------------
 Creating the Package File
@@ -61,7 +61,7 @@ we run ``spack create`` on it:
 
 And Spack should spawn a text editor with this file:
 
-.. literalinclude:: packaging_tutorial/0.package.py
+.. literalinclude:: tutorial/examples/0.package.py
    :start-after: # flake8: noqa
    :language: python
 
@@ -122,10 +122,10 @@ Let's remove some of the ``TODO`` comments, and add links to the mpileaks
 homepage and document what mpileaks does.  I'm also going to cut out the
 Copyright clause at this point to keep this tutorial document shorter,
 but you shouldn't do that normally.  The results of these changes can be
-found in ``$SPACK_ROOT/lib/spack/docs/packaging_tutorial/1.package.py``
+found in ``$SPACK_ROOT/lib/spack/docs/tutorial/examples/1.package.py``
 and are below.  Make these changes to your ``package.py``:
 
-.. literalinclude:: packaging_tutorial/1.package.py
+.. literalinclude:: tutorial/examples/1.package.py
    :start-after: # flake8: noqa
    :language: python
 
@@ -174,9 +174,9 @@ Dependencies
 The mpileaks packages depends on three other package: ``MPI``,
 ``adept-utils``, and ``callpath``.  Let's add those via the
 ``depends_on`` command in our ``package.py`` (this version is in
-``$SPACK_ROOT/lib/spack/docs/packaging_tutorial/2.package.py``):
+``$SPACK_ROOT/lib/spack/docs/tutorial/examples/2.package.py``):
 
-.. literalinclude:: packaging_tutorial/2.package.py
+.. literalinclude:: tutorial/examples/2.package.py
    :start-after: # flake8: noqa
    :language: python
 
@@ -329,9 +329,9 @@ Specifying Configure Arguments
 
 Let's add the configure arguments to the mpileaks' ``package.py``.  This
 version can be found in
-``$SPACK_ROOT/lib/spack/docs/packaging_tutorial/3.package.py``:
+``$SPACK_ROOT/lib/spack/docs/tutorial/examples/3.package.py``:
 
-.. literalinclude:: packaging_tutorial/3.package.py
+.. literalinclude:: tutorial/examples/3.package.py
    :start-after: # flake8: noqa
    :language: python
 
@@ -382,9 +382,9 @@ that it walks.  Let's add a variant to allow users to set this when they
 build in Spack.
 
 To do this, we'll add a variant to our package, as per the following (see
-``$SPACK_ROOT/lib/spack/docs/packaging_tutorial/4.package.py``):
+``$SPACK_ROOT/lib/spack/docs/tutorial/examples/4.package.py``):
 
-.. literalinclude:: packaging_tutorial/4.package.py
+.. literalinclude:: tutorial/examples/4.package.py
    :start-after: # flake8: noqa
    :language: python
 
diff --git a/lib/spack/docs/basic_usage_tutorial.rst b/lib/spack/docs/tutorial_sc16_spack_basics.rst
index cf8c654c0f..d83d6e4064 100644
--- a/lib/spack/docs/basic_usage_tutorial.rst
+++ b/lib/spack/docs/tutorial_sc16_spack_basics.rst
@@ -1,4 +1,4 @@
-.. _basics_tutorial:
+.. _basics-tutorial:
 
 =========================================
 Basic Installation Tutorial