tutorial: move tutorial to standalone site (#13450)

* docs: add a spack environment for building the docs

* docs: remove tutorial and link to spack-tutorial.readthedocs.io

The tutorial now has its own standalone website, versioned by instances
of the tutorial.  Link to that instead of versioning it directly with Spack.

lib/spack/docs/.gitignore

@@ -3,3 +3,5 @@ command_index.rst
 spack*.rst
 llnl*.rst
 _build
+.spack-env
+spack.lock

lib/spack/docs/build_systems/intelpackage.rst

@@ -802,7 +802,7 @@ by one of the following means:
   Configure the order of compilers in the appropriate ``packages.yaml`` file,
   under either an ``all:`` or client-package-specific entry, in a
   ``compiler:`` list. Consult the Spack documentation for
-  :ref:`Configuring Package Preferences <configs-tutorial-package-prefs>`
+  `Configuring Package Preferences <https://spack-tutorial.readthedocs.io/en/latest/tutorial_configuration.html#configuring-package-preferences>`_
   and
   :ref:`Concretization Preferences <concretization-preferences>`.
 
@@ -851,7 +851,7 @@ client packages, edit the ``packages.yaml`` file.  Customize, either in the
 the virtual packages and whose values are the Spack specs that satisfy the
 virtual package, in order of decreasing preference.  To learn more about the
 ``providers:`` settings, see the Spack tutorial for
-:ref:`Configuring Package Preferences <configs-tutorial-package-prefs>`
+`Configuring Package Preferences <https://spack-tutorial.readthedocs.io/en/latest/tutorial_configuration.html#configuring-package-preferences>`_
 and the section
 :ref:`Concretization Preferences <concretization-preferences>`.
 

lib/spack/docs/conf.py

@@ -159,7 +159,7 @@ def setup(sphinx):
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '_spack_root']
+exclude_patterns = ['_build', '_spack_root', '.spack-env']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None

lib/spack/docs/index.rst

@@ -55,7 +55,7 @@ or refer to the full manual below.
    getting_started
    basic_usage
    workflows
-   tutorial
+   Tutorial: Spack 101 <https://spack-tutorial.readthedocs.io>
    known_issues
 
 .. toctree::

lib/spack/docs/spack.yaml

+# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
+# Spack Project Developers. See the top-level COPYRIGHT file for details.
+#
+# SPDX-License-Identifier: (Apache-2.0 OR MIT)
+
+#
+# These are requirements for building the documentation.  You can run
+# these commands in this directory to install Sphinx and its plugins,
+# then build the docs:
+#
+#     spack install
+#     spack env activate .
+#     make
+#
+spack:
+  specs:
+  - py-sphinx
+  - py-sphinxcontrib-programoutput
+  - py-sphinx-rtd-theme

lib/spack/docs/tutorial.rst

-.. Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-   Spack Project Developers. See the top-level COPYRIGHT file for details.
-
-   SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-.. _spack-101:
-
-=============================
-Tutorial: Spack 101
-=============================
-
-This is a full-day introduction to Spack with lectures and live demos.
-It was last presented at the `Practice and Experience in Advanced
-Research Computing Conference (PEARC19)
-<https://www.pearc19.pearc.org/>`_ on July 31, 2019.
-
-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: https://spack.io/slides/spack-pearc19-tutorial-slides.pdf
-   :height: 72px
-   :align: left
-   :alt: Slide Preview
-
-`Download Slides <https://spack.io/slides/spack-pearc19-tutorial-slides.pdf>`_.
-
-**Full citation:** Levi Baber, Gregory Becker, Adam J. Stewart, and Todd
-Gamblin. Managing HPC Software Complexity with Spack.  Tutorial presented
-at the Practice and Experience in Advanced Research Computing Conference
-(PEARC19).  July 31, 2019.  Chicago, IL, USA.
-
-.. _sc16-live-demos:
-
-.. rubric:: Live Demos
-
-We provide scripts that take you step-by-step through basic Spack tasks.
-They correspond to sections in the slides above. You can use one of the
-following methods to run through the scripts:
-
-  1. We provide the `spack/tutorial
-     <https://hub.docker.com/r/spack/tutorial>`_ container image on
-     Docker Hub that you can use to do the tutorial on your local
-     machine.  You can invoke ``docker run -it spack/tutorial`` to start
-     using the container.
-
-  2. When we host the tutorial, we also provision VM instances in `AWS
-     <https://aws.amazon.com/>`_, so that users who are unfamiliar with
-     Docker can simply log into a VPM to do the demo exercises.
-
-You should now be ready to run through our demo scripts:
-
-  1. :ref:`basics-tutorial`
-  2. :ref:`configs-tutorial`
-  3. :ref:`packaging-tutorial`
-  4. :ref:`environments-tutorial`
-  5. :ref:`modules-tutorial`
-  6. :ref:`build-systems-tutorial`
-  7. :ref:`advanced-packaging-tutorial`
-
-Full contents:
-
-.. toctree::
-   tutorial_basics
-   tutorial_configuration
-   tutorial_packaging
-   tutorial_environments
-   tutorial_modules
-   tutorial_buildsystems
-   tutorial_advanced_packaging

lib/spack/docs/tutorial/examples/0.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-#
-# This is a template package file for Spack.  We've put "FIXME"
-# next to all the things you'll want to change. Once you've handled
-# them, you can save this file and test your package like this:
-#
-#     spack install mpileaks
-#
-# You can edit this file again by typing:
-#
-#     spack edit mpileaks
-#
-# See the Spack documentation for more information on packaging.
-# If you submit this package back to Spack as a pull request,
-# please first remove this boilerplate and all FIXME comments.
-#
-from spack import *
-
-
-class Mpileaks(Package):
-    """FIXME: Put a proper description of your package here."""
-
-    # FIXME: Add a proper url for your package's homepage here.
-    homepage = "http://www.example.com"
-    url      = "https://github.com/LLNL/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
-
-    version('1.0', sha256='2e34cc4505556d1c1f085758e26f2f8eea0972db9382f051b2dcfb1d7d9e1825')
-
-    # FIXME: Add dependencies if required.
-    # depends_on('foo')
-
-    def install(self, spec, prefix):
-        # FIXME: Unknown build system
-        make()
-        make('install')

lib/spack/docs/tutorial/examples/1.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Mpileaks(Package):
-    """Tool to detect and report MPI objects like MPI_Requests and
-    MPI_Datatypes."""
-
-    homepage = "https://github.com/LLNL/mpileaks"
-    url      = "https://github.com/LLNL/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
-
-    version('1.0', sha256='2e34cc4505556d1c1f085758e26f2f8eea0972db9382f051b2dcfb1d7d9e1825')
-
-    # FIXME: Add dependencies if required.
-    # depends_on('foo')
-
-    def install(self, spec, prefix):
-        # FIXME: Unknown build system
-        make()
-        make('install')

lib/spack/docs/tutorial/examples/2.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Mpileaks(Package):
-    """Tool to detect and report MPI objects like MPI_Requests and
-    MPI_Datatypes."""
-
-    homepage = "https://github.com/LLNL/mpileaks"
-    url      = "https://github.com/LLNL/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
-
-    version('1.0', sha256='2e34cc4505556d1c1f085758e26f2f8eea0972db9382f051b2dcfb1d7d9e1825')
-
-    depends_on('mpi')
-    depends_on('adept-utils')
-    depends_on('callpath')
-
-    def install(self, spec, prefix):
-        # FIXME: Unknown build system
-        make()
-        make('install')

lib/spack/docs/tutorial/examples/3.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Mpileaks(Package):
-    """Tool to detect and report MPI objects like MPI_Requests and
-    MPI_Datatypes."""
-
-    homepage = "https://github.com/LLNL/mpileaks"
-    url      = "https://github.com/LLNL/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
-
-    version('1.0', sha256='2e34cc4505556d1c1f085758e26f2f8eea0972db9382f051b2dcfb1d7d9e1825')
-
-    depends_on('mpi')
-    depends_on('adept-utils')
-    depends_on('callpath')
-
-    def install(self, spec, prefix):
-        configure()
-        make()
-        make('install')

lib/spack/docs/tutorial/examples/4.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Mpileaks(Package):
-    """Tool to detect and report MPI objects like MPI_Requests and
-    MPI_Datatypes."""
-
-    homepage = "https://github.com/LLNL/mpileaks"
-    url      = "https://github.com/LLNL/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
-
-    version('1.0', sha256='2e34cc4505556d1c1f085758e26f2f8eea0972db9382f051b2dcfb1d7d9e1825')
-
-    depends_on('mpi')
-    depends_on('adept-utils')
-    depends_on('callpath')
-
-    def install(self, spec, prefix):
-        configure('--prefix={0}'.format(prefix),
-                  '--with-adept-utils={0}'.format(spec['adept-utils'].prefix),
-                  '--with-callpath={0}'.format(spec['callpath'].prefix))
-        make()
-        make('install')

lib/spack/docs/tutorial/examples/5.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Mpileaks(Package):
-    """Tool to detect and report MPI objects like MPI_Requests and
-    MPI_Datatypes."""
-
-    homepage = "https://github.com/LLNL/mpileaks"
-    url      = "https://github.com/LLNL/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
-
-    version('1.0', sha256='2e34cc4505556d1c1f085758e26f2f8eea0972db9382f051b2dcfb1d7d9e1825')
-
-    variant('stackstart', values=int, default=0,
-            description='Specify the number of stack frames to truncate')
-
-    depends_on('mpi')
-    depends_on('adept-utils')
-    depends_on('callpath')
-
-    def install(self, spec, prefix):
-        stackstart = int(spec.variants['stackstart'].value)
-
-        args = [
-            '--prefix={0}'.format(prefix),
-            '--with-adept-utils={0}'.format(spec['adept-utils'].prefix),
-            '--with-callpath={0}'.format(spec['callpath'].prefix),
-        ]
-
-        if stackstart:
-            args.extend([
-                '--with-stack-start-c={0}'.format(stackstart),
-                '--with-stack-start-fortran={0}'.format(stackstart)
-            ])
-
-        configure(*args)
-        make()
-        make('install')

lib/spack/docs/tutorial/examples/Autotools/0.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Mpileaks(AutotoolsPackage):
-    """Tool to detect and report leaked MPI objects like MPI_Requests and
-       MPI_Datatypes."""
-
-    homepage = "https://github.com/hpc/mpileaks"
-    url      = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
-
-    version('1.0', '8838c574b39202a57d7c2d68692718aa')
-
-    depends_on("mpi")
-    depends_on("adept-utils")
-    depends_on("callpath")
-
-    def install(self, spec, prefix):
-        configure("--prefix=" + prefix,
-                  "--with-adept-utils=" + spec['adept-utils'].prefix,
-                  "--with-callpath=" + spec['callpath'].prefix)
-        make()
-        make("install")

lib/spack/docs/tutorial/examples/Autotools/1.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Mpileaks(AutotoolsPackage):
-    """Tool to detect and report leaked MPI objects like MPI_Requests and
-       MPI_Datatypes."""
-
-    homepage = "https://github.com/hpc/mpileaks"
-    url      = "https://github.com/hpc/mpileaks/releases/download/v1.0/mpileaks-1.0.tar.gz"
-
-    version('1.0', '8838c574b39202a57d7c2d68692718aa')
-
-    variant("stackstart", values=int, default=0,
-            description="Specify the number of stack frames to truncate")
-
-    depends_on("mpi")
-    depends_on("adept-utils")
-    depends_on("callpath")
-
-    def configure_args(self):
-        stackstart = int(self.spec.variants['stackstart'].value)
-        args = ["--with-adept-utils=" + spec['adept-utils'].prefix,
-                "--with-callpath=" + spec['callpath'].prefix]
-        if stackstart:
-            args.extend(['--with-stack-start-c=%s' % stackstart,
-                         '--with-stack-start-fortran=%s' % stackstart])
-        return args

lib/spack/docs/tutorial/examples/Cmake/0.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-#
-# This is a template package file for Spack.  We've put "FIXME"
-# next to all the things you'll want to change. Once you've handled
-# them, you can save this file and test your package like this:
-#
-#     spack install callpath
-#
-# You can edit this file again by typing:
-#
-#     spack edit callpath
-#
-# See the Spack documentation for more information on packaging.
-# If you submit this package back to Spack as a pull request,
-# please first remove this boilerplate and all FIXME comments.
-#
-from spack import *
-
-
-class Callpath(CMakePackage):
-    """FIXME: Put a proper description of your package here."""
-
-    # FIXME: Add a proper url for your package's homepage here.
-    homepage = "http://www.example.com"
-    url      = "https://github.com/llnl/callpath/archive/v1.0.1.tar.gz"
-
-    version('1.0.3', 'c89089b3f1c1ba47b09b8508a574294a')
-
-    # FIXME: Add dependencies if required.
-    # depends_on('foo')
-
-    def cmake_args(self):
-        # FIXME: Add arguments other than
-        # FIXME: CMAKE_INSTALL_PREFIX and CMAKE_BUILD_TYPE
-        # FIXME: If not needed delete this function
-        args = []
-        return args

lib/spack/docs/tutorial/examples/Cmake/1.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Callpath(CMakePackage):
-    """Library for representing callpaths consistently in
-       distributed-memory performance tools."""
-
-    homepage = "https://github.com/llnl/callpath"
-    url      = "https://github.com/llnl/callpath/archive/v1.0.3.tar.gz"
-
-    version('1.0.3', 'c89089b3f1c1ba47b09b8508a574294a')
-
-    depends_on("elf", type="link")
-    depends_on("libdwarf")
-    depends_on("dyninst")
-    depends_on("adept-utils")
-    depends_on("mpi")
-    depends_on("cmake@2.8:", type="build")

lib/spack/docs/tutorial/examples/Cmake/2.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Callpath(CMakePackage):
-    """Library for representing callpaths consistently in
-       distributed-memory performance tools."""
-
-    homepage = "https://github.com/llnl/callpath"
-    url      = "https://github.com/llnl/callpath/archive/v1.0.3.tar.gz"
-
-    version('1.0.3', 'c89089b3f1c1ba47b09b8508a574294a')
-
-    depends_on("elf", type="link")
-    depends_on("libdwarf")
-    depends_on("dyninst")
-    depends_on("adept-utils")
-    depends_on("mpi")
-    depends_on("cmake@2.8:", type="build")
-
-    def cmake_args(self):
-        args = ["-DCALLPATH_WALKER=dyninst"]
-
-        if self.spec.satisfies("^dyninst@9.3.0:"):
-            std.flag = self.compiler.cxx_flag
-            args.append("-DCMAKE_CXX_FLAGS='{0}' -fpermissive'".format(
-                std_flag))
-
-        return args

lib/spack/docs/tutorial/examples/Makefile/0.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Bowtie(MakefilePackage):
-    """FIXME: Put a proper description of your package here."""
-
-    # FIXME: Add a proper url for your package's homepage here.
-    homepage = "http://www.example.com"
-    url      = "https://downloads.sourceforge.net/project/bowtie-bio/bowtie/1.2.1.1/bowtie-1.2.1.1-src.zip"
-
-    version('1.2.1.1', 'ec06265730c5f587cd58bcfef6697ddf')
-
-    # FIXME: Add dependencies if required.
-    # depends_on('foo')
-
-    def edit(self, spec, prefix):
-        # FIXME: Edit the Makefile if necessary
-        # FIXME: If not needed delete this function
-        # makefile = FileFilter('Makefile')
-        # makefile.filter('CC = .*', 'CC = cc')
-        return

lib/spack/docs/tutorial/examples/Makefile/1.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Bowtie(MakefilePackage):
-    """Bowtie is an ultrafast, memory efficient short read aligner
-    for short DNA sequences (reads) from next-gen sequencers."""
-
-    homepage = "https://sourceforge.net/projects/bowtie-bio/"
-    url      = "https://downloads.sourceforge.net/project/bowtie-bio/bowtie/1.2.1.1/bowtie-1.2.1.1-src.zip"
-
-    version('1.2.1.1', 'ec06265730c5f587cd58bcfef6697ddf')
-
-    variant("tbb", default=False, description="Use Intel thread building block")
-
-    depends_on("tbb", when="+tbb")
-
-    def edit(self, spec, prefix):
-        # FIXME: Edit the Makefile if necessary
-        # FIXME: If not needed delete this function
-        # makefile = FileFilter('Makefile')
-        # makefile.filter('CC = .*', 'CC = cc')
-        return

lib/spack/docs/tutorial/examples/Makefile/2.package.py

-# Copyright 2013-2019 Lawrence Livermore National Security, LLC and other
-# Spack Project Developers. See the top-level COPYRIGHT file for details.
-#
-# SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-from spack import *
-
-
-class Bowtie(MakefilePackage):
-    """Bowtie is an ultrafast, memory efficient short read aligner
-    for short DNA sequences (reads) from next-gen sequencers."""
-
-    homepage = "https://sourceforge.net/projects/bowtie-bio/"
-    url      = "https://downloads.sourceforge.net/project/bowtie-bio/bowtie/1.2.1.1/bowtie-1.2.1.1-src.zip"
-
-    version('1.2.1.1', 'ec06265730c5f587cd58bcfef6697ddf')
-
-    variant("tbb", default=False, description="Use Intel thread building block")
-
-    depends_on("tbb", when="+tbb")
-
-    def edit(self, spec, prefix):
-        makefile = FileFilter("Makefile")
-        makefile.filter('CC= .*', 'CC = ' + env['CC'])
-        makefile.filter('CXX = .*', 'CXX = ' + env['CXX'])