From f32843528e52dc40c6a379f03d69b06f8a52265f Mon Sep 17 00:00:00 2001 From: Todd Gamblin Date: Tue, 21 May 2019 23:45:54 -0700 Subject: 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 --- lib/spack/docs/_spack_root | 1 + lib/spack/docs/conf.py | 36 ++++++++++++++++---------- lib/spack/docs/config_yaml.rst | 2 +- lib/spack/docs/features.rst | 2 +- lib/spack/docs/module_file_support.rst | 6 ++--- lib/spack/docs/packaging_guide.rst | 20 +++++++------- lib/spack/docs/tutorial_buildsystems.rst | 8 +++--- lib/spack/docs/tutorial_configuration.rst | 4 +-- lib/spack/docs/tutorial_modules.rst | 6 ++--- lib/spack/spack/schema/compilers.py | 2 +- lib/spack/spack/schema/config.py | 2 +- lib/spack/spack/schema/env.py | 2 +- lib/spack/spack/schema/merged.py | 2 +- lib/spack/spack/schema/mirrors.py | 2 +- lib/spack/spack/schema/modules.py | 2 +- lib/spack/spack/schema/os_container_mapping.py | 2 +- lib/spack/spack/schema/packages.py | 2 +- lib/spack/spack/schema/projections.py | 2 +- lib/spack/spack/schema/repos.py | 2 +- lib/spack/spack/schema/spec_set.py | 2 +- lib/spack/spack/schema/specs_deps.py | 2 +- 21 files changed, 59 insertions(+), 50 deletions(-) create mode 120000 lib/spack/docs/_spack_root (limited to 'lib') 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- """ -- cgit v1.2.3-60-g2f50