zhangyiss/spack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: make docs build relocatable for localized builds

Browse Source 
- 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
This commit is contained in:
Todd Gamblin 2019-05-21 23:45:54 -07:00
parent 8bf1bd4637
commit f32843528e
21 changed files with 59 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
lib/spack/docs/_spack_root Symbolic link
View File

@ -0,0 +1 @@
../../..

36
lib/spack/docs/conf.py
View File

@ -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 @@
'--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 @@ def setup(sphinx):
# 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 @@ 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']
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 @@ def setup(sphinx):
# 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,

2
lib/spack/docs/config_yaml.rst
View File

@ -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

2
lib/spack/docs/features.rst
View File

@ -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

6
lib/spack/docs/module_file_support.rst
View File

@ -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

20
lib/spack/docs/packaging_guide.rst
View File

@ -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

8
lib/spack/docs/tutorial_buildsystems.rst
View File

@ -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:

4
lib/spack/docs/tutorial_configuration.rst
View File

@ -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

6
lib/spack/docs/tutorial_modules.rst
View File

@ -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

2
lib/spack/spack/schema/compilers.py
View File

@ -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-
"""

2
lib/spack/spack/schema/config.py
View File

@ -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-
"""

2
lib/spack/spack/schema/env.py
View File

@ -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

2
lib/spack/spack/schema/merged.py
View File

@ -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

2
lib/spack/spack/schema/mirrors.py
View File

@ -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-
"""

2
lib/spack/spack/schema/modules.py
View File

@ -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-
"""

2
lib/spack/spack/schema/os_container_mapping.py
View File

@ -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-
"""

2
lib/spack/spack/schema/packages.py
View File

@ -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-
"""

2
lib/spack/spack/schema/projections.py
View File

@ -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-
"""

2
lib/spack/spack/schema/repos.py
View File

@ -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-
"""

2
lib/spack/spack/schema/spec_set.py
View File

@ -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-
"""

2
lib/spack/spack/schema/specs_deps.py
View File

@ -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-
"""