diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst index 65fb995d1eb2edd55fb2ee6e6009f59879021998..ed2ff96ed0b0443108d2ceffb347e8c636310430 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 0000000000000000000000000000000000000000..71905cea7d3658e0790699b21cbab500a9790a48 --- /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 0000000000000000000000000000000000000000..12dd4fe06f44a328deb4e62fe0328ba63d27a340 Binary files /dev/null and b/lib/spack/docs/tutorial/Spack-SC16-Tutorial.pdf differ diff --git a/lib/spack/docs/packaging_tutorial/0.package.py b/lib/spack/docs/tutorial/examples/0.package.py similarity index 100% rename from lib/spack/docs/packaging_tutorial/0.package.py rename to 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 similarity index 100% rename from lib/spack/docs/packaging_tutorial/1.package.py rename to 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 similarity index 100% rename from lib/spack/docs/packaging_tutorial/2.package.py rename to 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 similarity index 100% rename from lib/spack/docs/packaging_tutorial/3.package.py rename to 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 similarity index 100% rename from lib/spack/docs/packaging_tutorial/4.package.py rename to 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 0000000000000000000000000000000000000000..e7f9b2e323065e8cbdc200ce344d4fd99e145dd1 Binary files /dev/null and b/lib/spack/docs/tutorial/sc16-tutorial-slide-preview.png differ diff --git a/lib/spack/docs/tutorial_sc16.rst b/lib/spack/docs/tutorial_sc16.rst new file mode 100644 index 0000000000000000000000000000000000000000..e8cf3aeebedcc93bf4085a419051755916bffe1e --- /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 similarity index 99% rename from lib/spack/docs/module_file_tutorial.rst rename to lib/spack/docs/tutorial_sc16_modules.rst index 83df756566d0fcc86d6868bbee761f412d793b2f..1e786674bb0e9484404155d10713b832a4f0f84d 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 similarity index 97% rename from lib/spack/docs/package_tutorial.rst rename to lib/spack/docs/tutorial_sc16_packaging.rst index e955780345bdeb84b15ca2e40378ff90c52d653e..41c938327efb6bc98909ecb0ae2535fcbaae55ae 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 similarity index 99% rename from lib/spack/docs/basic_usage_tutorial.rst rename to lib/spack/docs/tutorial_sc16_spack_basics.rst index cf8c654c0f3a9c83562276ae145bb0f4444d21ac..d83d6e40641d8030baafbfd5bdd99a0f7fa6f41f 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