docs: make docs build relocatable for localized builds

- make all Spack paths relative to a `_spack_root` symlink, so that we
  can easily relocate the docs build *outside* lib/spack/docs

- set some useful defaults for gettext translation variables in conf.py

- update `relativeinclude` and other references to the spack root in the
  RST files to use _spack_root

21 files changed, 59 insertions, 50 deletions

diff --git a/lib/spack/docs/_spack_root b/lib/spack/docs/_spack_root
new file mode 120000
index 0000000000..a8a4f8c212
--- /dev/null
+++ b/lib/spack/docs/_spack_root
@@ -0,0 +1 @@
+../../..
\ No newline at end of file
diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
index ea1a100495..7b5ebcbb12 100644
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -20,28 +20,29 @@
 import sys
 import os
 import re
-import shutil
 import subprocess
 from glob import glob
 
 from sphinx.ext.apidoc import main as sphinx_apidoc
 
 # -- Spack customizations -----------------------------------------------------
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath('../external'))
+sys.path.insert(0, os.path.abspath('_spack_root/lib/spack/external'))
+
 if sys.version_info[0] < 3:
-    sys.path.insert(0, os.path.abspath('../external/yaml/lib'))
+    sys.path.insert(
+        0, os.path.abspath('_spack_root/lib/spack/external/yaml/lib'))
 else:
-    sys.path.insert(0, os.path.abspath('../external/yaml/lib3'))
-sys.path.append(os.path.abspath('..'))
+    sys.path.insert(
+        0, os.path.abspath('_spack_root/lib/spack/external/yaml/lib3'))
+
+sys.path.append(os.path.abspath('_spack_root/lib/spack/'))
 
 # Add the Spack bin directory to the path so that we can use its output in docs.
-spack_root = '../../..'
-os.environ['SPACK_ROOT'] = spack_root
-os.environ['PATH'] += '%s%s/bin' % (os.pathsep, spack_root)
+os.environ['SPACK_ROOT'] = os.path.abspath('_spack_root')
+os.environ['PATH'] += "%s%s" % (os.pathsep, os.path.abspath('_spack_root/bin'))
 
 # Set an environment variable so that colify will print output like it would to
 # a terminal.
@@ -72,8 +73,8 @@ apidoc_args = [
     '--no-toc',        # Don't create a table of contents file
     '--output-dir=.',  # Directory to place all output
 ]
-sphinx_apidoc(apidoc_args + ['../spack'])
-sphinx_apidoc(apidoc_args + ['../llnl'])
+sphinx_apidoc(apidoc_args + ['_spack_root/lib/spack/spack'])
+sphinx_apidoc(apidoc_args + ['_spack_root/lib/spack/llnl'])
 
 # Enable todo items
 todo_include_todos = True
@@ -144,6 +145,13 @@ release = spack.spack_version
 # for a list of supported languages.
 #language = None
 
+# Places to look for .po/.mo files for doc translations
+#locale_dirs = []
+
+# Sphinx gettext settings
+gettext_compact = True
+gettext_uuid = True
+
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
@@ -152,7 +160,7 @@ release = spack.spack_version
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ['_build', '_spack_root']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None
@@ -198,12 +206,12 @@ html_theme_options = { 'logo_only' : True }
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-html_logo = '../../../share/spack/logo/spack-logo-white-text.svg'
+html_logo = '_spack_root/share/spack/logo/spack-logo-white-text.svg'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = '../../../share/spack/logo/favicon.ico'
+html_favicon = '_spack_root/share/spack/logo/favicon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
diff --git a/lib/spack/docs/config_yaml.rst b/lib/spack/docs/config_yaml.rst
index ad2ff736af..54a793b53f 100644
--- a/lib/spack/docs/config_yaml.rst
+++ b/lib/spack/docs/config_yaml.rst
@@ -13,7 +13,7 @@ Spack's basic configuration options are set in ``config.yaml``.  You can
 see the default settings by looking at
 ``etc/spack/defaults/config.yaml``:
 
-.. literalinclude:: ../../../etc/spack/defaults/config.yaml
+.. literalinclude:: _spack_root/etc/spack/defaults/config.yaml
    :language: yaml
 
 These settings can be overridden in ``etc/spack/config.yaml`` or
diff --git a/lib/spack/docs/features.rst b/lib/spack/docs/features.rst
index 63f2080c8a..c4de4ef416 100644
--- a/lib/spack/docs/features.rst
+++ b/lib/spack/docs/features.rst
@@ -130,7 +130,7 @@ creates a simple python file:
 It doesn't take much python coding to get from there to a working
 package:
 
-.. literalinclude:: ../../../var/spack/repos/builtin/packages/libelf/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/libelf/package.py
    :lines: 6-
 
 Spack also provides wrapper functions around common commands like
diff --git a/lib/spack/docs/module_file_support.rst b/lib/spack/docs/module_file_support.rst
index 2335fc73bb..85221dd2f8 100644
--- a/lib/spack/docs/module_file_support.rst
+++ b/lib/spack/docs/module_file_support.rst
@@ -355,14 +355,14 @@ list of environment modifications.
 
   with the following snippet:
 
-  .. literalinclude:: ../../../var/spack/repos/builtin/packages/r/package.py
+  .. literalinclude:: _spack_root/var/spack/repos/builtin/packages/r/package.py
      :pyobject: R.setup_environment
 
   The ``r`` package also knows which environment variable should be modified
   to make language extensions provided by other packages available, and modifies
   it appropriately in the override of the second method:
 
-  .. literalinclude:: ../../../var/spack/repos/builtin/packages/r/package.py
+  .. literalinclude:: _spack_root/var/spack/repos/builtin/packages/r/package.py
      :pyobject: R.setup_dependent_environment
 
 .. _modules-yaml:
@@ -374,7 +374,7 @@ Write a configuration file
 The configuration files that control module generation behavior
 are named ``modules.yaml``. The default configuration:
 
-.. literalinclude:: ../../../etc/spack/defaults/modules.yaml
+.. literalinclude:: _spack_root/etc/spack/defaults/modules.yaml
    :language: yaml
 
 activates the hooks to generate ``tcl`` and ``dotkit`` module files and inspects
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 898dd1442c..a8ec76e6cd 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -460,7 +460,7 @@ https://www.open-mpi.org/software/ompi/v2.1/downloads/openmpi-2.1.1.tar.bz2
 In order to handle this, you can define a ``url_for_version()`` function
 like so:
 
-.. literalinclude:: ../../../var/spack/repos/builtin/packages/openmpi/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/openmpi/package.py
    :pyobject: Openmpi.url_for_version
 
 With the use of this ``url_for_version()``, Spack knows to download OpenMPI ``2.1.1``
@@ -1565,7 +1565,7 @@ handles ``RPATH``:
 
 .. _pyside-patch:
 
-.. literalinclude:: ../../../var/spack/repos/builtin/packages/py-pyside/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/py-pyside/package.py
    :pyobject: PyPyside.patch
    :linenos:
 
@@ -2027,7 +2027,7 @@ properties to be used by dependents.
 
 The function declaration should look like this:
 
-.. literalinclude:: ../../../var/spack/repos/builtin/packages/qt/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/qt/package.py
    :pyobject: Qt.setup_dependent_environment
    :linenos:
 
@@ -2047,7 +2047,7 @@ The arguments to this function are:
 
 A good example of using these is in the Python package:
 
-.. literalinclude:: ../../../var/spack/repos/builtin/packages/python/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/python/package.py
    :pyobject: Python.setup_dependent_environment
    :linenos:
 
@@ -2209,7 +2209,7 @@ same way that Python does.
 
 Let's look at Python's activate function:
 
-.. literalinclude:: ../../../var/spack/repos/builtin/packages/python/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/python/package.py
    :pyobject: Python.activate
    :linenos:
 
@@ -2221,7 +2221,7 @@ Python's setuptools.
 
 Deactivate behaves similarly to activate, but it unlinks files:
 
-.. literalinclude:: ../../../var/spack/repos/builtin/packages/python/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/python/package.py
    :pyobject: Python.deactivate
    :linenos:
 
@@ -2663,7 +2663,7 @@ docs at :py:mod:`~.spack.build_systems`, or using the ``spack info`` command:
 
 Typically, phases have default implementations that fit most of the common cases:
 
-.. literalinclude:: ../../../lib/spack/spack/build_systems/autotools.py
+.. literalinclude:: _spack_root/lib/spack/spack/build_systems/autotools.py
     :pyobject: AutotoolsPackage.configure
     :linenos:
 
@@ -2671,7 +2671,7 @@ It is thus just sufficient for a packager to override a few
 build system specific helper methods or attributes to provide, for instance,
 configure arguments:
 
-.. literalinclude::  ../../../var/spack/repos/builtin/packages/m4/package.py
+.. literalinclude::  _spack_root/var/spack/repos/builtin/packages/m4/package.py
     :pyobject: M4.configure_args
     :linenos:
 
@@ -2846,7 +2846,7 @@ Shell command functions
 
 Recall the install method from ``libelf``:
 
-.. literalinclude::  ../../../var/spack/repos/builtin/packages/libelf/package.py
+.. literalinclude::  _spack_root/var/spack/repos/builtin/packages/libelf/package.py
    :pyobject: Libelf.install
    :linenos:
 
@@ -3505,7 +3505,7 @@ the one passed to install, only the MPI implementations all set some
 additional properties on it to help you out.  E.g., in mvapich2, you'll
 find this:
 
-.. literalinclude:: ../../../var/spack/repos/builtin/packages/mvapich2/package.py
+.. literalinclude:: _spack_root/var/spack/repos/builtin/packages/mvapich2/package.py
    :pyobject: Mvapich2.setup_dependent_package
 
 That code allows the mvapich2 package to associate an ``mpicc`` property
diff --git a/lib/spack/docs/tutorial_buildsystems.rst b/lib/spack/docs/tutorial_buildsystems.rst
index 52d6edeaeb..9f3785e7ee 100644
--- a/lib/spack/docs/tutorial_buildsystems.rst
+++ b/lib/spack/docs/tutorial_buildsystems.rst
@@ -108,7 +108,7 @@ This will open the :code:`AutotoolsPackage` file in your text editor.
     long examples. We only show what is relevant to the packager.
 
 
-.. literalinclude:: ../../../lib/spack/spack/build_systems/autotools.py
+.. literalinclude:: _spack_root/lib/spack/spack/build_systems/autotools.py
     :language: python
     :emphasize-lines: 33,36,54
     :lines: 30-76,240-248
@@ -207,7 +207,7 @@ Let's also take a look inside the :code:`MakefilePackage` class:
 Take note of the following:
 
 
-.. literalinclude:: ../../../lib/spack/spack/build_systems/makefile.py
+.. literalinclude:: _spack_root/lib/spack/spack/build_systems/makefile.py
    :language: python
    :lines: 14,43-61,70-88
    :emphasize-lines: 21,27,34
@@ -494,7 +494,7 @@ Let's look at these defaults in the :code:`CMakePackage` class in the :code:`_st
 
     $ spack edit --build-system cmake
 
-.. literalinclude:: ../../../lib/spack/spack/build_systems/cmake.py
+.. literalinclude:: _spack_root/lib/spack/spack/build_systems/cmake.py
    :language: python
    :lines: 102-147
    :emphasize-lines: 10,18,24,36,37,38,44
@@ -694,7 +694,7 @@ at the :code:`PythonPackage` class:
 We see the following:
 
 
-.. literalinclude:: ../../../lib/spack/spack/build_systems/python.py
+.. literalinclude:: _spack_root/lib/spack/spack/build_systems/python.py
    :language: python
    :lines: 19,146-357
    :linenos:
diff --git a/lib/spack/docs/tutorial_configuration.rst b/lib/spack/docs/tutorial_configuration.rst
index 52f789a763..d6559f3d79 100644
--- a/lib/spack/docs/tutorial_configuration.rst
+++ b/lib/spack/docs/tutorial_configuration.rst
@@ -392,7 +392,7 @@ configuration file. First, we will look at the default
    $ spack config --scope defaults edit packages
 
 
-.. literalinclude:: ../../../etc/spack/defaults/packages.yaml
+.. literalinclude:: _spack_root/etc/spack/defaults/packages.yaml
    :language: yaml
 
 
@@ -829,7 +829,7 @@ running:
    $ spack config --scope defaults edit config
 
 
-.. literalinclude:: ../../../etc/spack/defaults/config.yaml
+.. literalinclude:: _spack_root/etc/spack/defaults/config.yaml
    :language: yaml
 
 
diff --git a/lib/spack/docs/tutorial_modules.rst b/lib/spack/docs/tutorial_modules.rst
index 8487a03759..686da9f26e 100644
--- a/lib/spack/docs/tutorial_modules.rst
+++ b/lib/spack/docs/tutorial_modules.rst
@@ -1423,7 +1423,7 @@ they all share the same common structure.  Usually, they start with a
 header that identifies the type of module being generated. In the case of
 hierarchical module files it's:
 
-.. literalinclude:: ../../../share/spack/templates/modules/modulefile.lua
+.. literalinclude:: _spack_root/share/spack/templates/modules/modulefile.lua
   :language: jinja
   :lines: 1-6
 
@@ -1437,14 +1437,14 @@ that can be overridden or extended by users, if need be.
 , delimited by ``{% ... %}``,
 are also permitted in the template language:
 
-.. literalinclude:: ../../../share/spack/templates/modules/modulefile.lua
+.. literalinclude:: _spack_root/share/spack/templates/modules/modulefile.lua
   :language: jinja
   :lines: 73-88
 
 The locations where Spack looks for templates are specified
 in ``config.yaml``:
 
-.. literalinclude:: ../../../etc/spack/defaults/config.yaml
+.. literalinclude:: _spack_root/etc/spack/defaults/config.yaml
   :language: yaml
   :lines: 21-24
 
diff --git a/lib/spack/spack/schema/compilers.py b/lib/spack/spack/schema/compilers.py
index 90ebe8f29b..69659917ff 100644
--- a/lib/spack/spack/schema/compilers.py
+++ b/lib/spack/spack/schema/compilers.py
@@ -5,7 +5,7 @@
 
 """Schema for compilers.yaml configuration file.
 
-.. literalinclude:: ../spack/schema/compilers.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/compilers.py
    :lines: 13-
 """
 
diff --git a/lib/spack/spack/schema/config.py b/lib/spack/spack/schema/config.py
index 30c0bf0591..31e7f9b283 100644
--- a/lib/spack/spack/schema/config.py
+++ b/lib/spack/spack/schema/config.py
@@ -5,7 +5,7 @@
 
 """Schema for config.yaml configuration file.
 
-.. literalinclude:: ../spack/schema/config.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/config.py
    :lines: 13-
 """
 
diff --git a/lib/spack/spack/schema/env.py b/lib/spack/spack/schema/env.py
index 9fbc59219c..91931ec90c 100644
--- a/lib/spack/spack/schema/env.py
+++ b/lib/spack/spack/schema/env.py
@@ -5,7 +5,7 @@
 
 """Schema for env.yaml configuration file.
 
-.. literalinclude:: ../spack/schema/env.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/env.py
    :lines: 36-
 """
 from llnl.util.lang import union_dicts
diff --git a/lib/spack/spack/schema/merged.py b/lib/spack/spack/schema/merged.py
index 1832848f77..148f6e5417 100644
--- a/lib/spack/spack/schema/merged.py
+++ b/lib/spack/spack/schema/merged.py
@@ -5,7 +5,7 @@
 
 """Schema for configuration merged into one file.
 
-.. literalinclude:: ../spack/schema/merged.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/merged.py
    :lines: 39-
 """
 from llnl.util.lang import union_dicts
diff --git a/lib/spack/spack/schema/mirrors.py b/lib/spack/spack/schema/mirrors.py
index 1d0f367275..551267bd4f 100644
--- a/lib/spack/spack/schema/mirrors.py
+++ b/lib/spack/spack/schema/mirrors.py
@@ -5,7 +5,7 @@
 
 """Schema for mirrors.yaml configuration file.
 
-.. literalinclude:: ../spack/schema/mirrors.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/mirrors.py
    :lines: 13-
 """
 
diff --git a/lib/spack/spack/schema/modules.py b/lib/spack/spack/schema/modules.py
index 0c9b14a8c5..1da9dbd586 100644
--- a/lib/spack/spack/schema/modules.py
+++ b/lib/spack/spack/schema/modules.py
@@ -5,7 +5,7 @@
 
 """Schema for modules.yaml configuration file.
 
-.. literalinclude:: ../spack/schema/modules.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/modules.py
    :lines: 13-
 """
 
diff --git a/lib/spack/spack/schema/os_container_mapping.py b/lib/spack/spack/schema/os_container_mapping.py
index 0476e98945..a69549d51d 100644
--- a/lib/spack/spack/schema/os_container_mapping.py
+++ b/lib/spack/spack/schema/os_container_mapping.py
@@ -5,7 +5,7 @@
 
 """Schema for os-container-mapping.yaml configuration file.
 
-.. literalinclude:: ../spack/schema/os_container_mapping.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/os_container_mapping.py
    :lines: 32-
 """
 
diff --git a/lib/spack/spack/schema/packages.py b/lib/spack/spack/schema/packages.py
index 93b4c03f2f..c276c4a174 100644
--- a/lib/spack/spack/schema/packages.py
+++ b/lib/spack/spack/schema/packages.py
@@ -5,7 +5,7 @@
 
 """Schema for packages.yaml configuration files.
 
-.. literalinclude:: ../spack/schema/packages.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/packages.py
    :lines: 13-
 """
 
diff --git a/lib/spack/spack/schema/projections.py b/lib/spack/spack/schema/projections.py
index b8aadd7379..f076ed473b 100644
--- a/lib/spack/spack/schema/projections.py
+++ b/lib/spack/spack/schema/projections.py
@@ -5,7 +5,7 @@
 
 """Schema for projections.yaml configuration file.
 
-.. literalinclude:: ../spack/schema/projections.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/projections.py
    :lines: 13-
 """
 
diff --git a/lib/spack/spack/schema/repos.py b/lib/spack/spack/schema/repos.py
index d078c4b57b..fe74942872 100644
--- a/lib/spack/spack/schema/repos.py
+++ b/lib/spack/spack/schema/repos.py
@@ -5,7 +5,7 @@
 
 """Schema for repos.yaml configuration file.
 
-.. literalinclude:: ../spack/schema/repos.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/repos.py
    :lines: 13-
 """
 
diff --git a/lib/spack/spack/schema/spec_set.py b/lib/spack/spack/schema/spec_set.py
index 6f15a86376..70ba8de71f 100644
--- a/lib/spack/spack/schema/spec_set.py
+++ b/lib/spack/spack/schema/spec_set.py
@@ -5,7 +5,7 @@
 
 """Schema for Spack spec-set configuration file.
 
-.. literalinclude:: ../spack/schema/spec_set.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/spec_set.py
    :lines: 32-
 """
 
diff --git a/lib/spack/spack/schema/specs_deps.py b/lib/spack/spack/schema/specs_deps.py
index c6981837ee..0ac029c25a 100644
--- a/lib/spack/spack/schema/specs_deps.py
+++ b/lib/spack/spack/schema/specs_deps.py
@@ -5,7 +5,7 @@
 
 """Schema for expressing dependencies of a set of specs in a JSON file
 
-.. literalinclude:: ../spack/schema/specs_deps.py
+.. literalinclude:: _spack_root/lib/spack/spack/schema/specs_deps.py
    :lines: 32-
 """