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 sys
import os import os
import re import re
import shutil
import subprocess import subprocess
from glob import glob from glob import glob
from sphinx.ext.apidoc import main as sphinx_apidoc from sphinx.ext.apidoc import main as sphinx_apidoc
# -- Spack customizations ----------------------------------------------------- # -- Spack customizations -----------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory, # 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 # 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. # 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: 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: else:
sys.path.insert(0, os.path.abspath('../external/yaml/lib3')) sys.path.insert(
sys.path.append(os.path.abspath('..')) 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. # Add the Spack bin directory to the path so that we can use its output in docs.
spack_root = '../../..' os.environ['SPACK_ROOT'] = os.path.abspath('_spack_root')
os.environ['SPACK_ROOT'] = spack_root os.environ['PATH'] += "%s%s" % (os.pathsep, os.path.abspath('_spack_root/bin'))
os.environ['PATH'] += '%s%s/bin' % (os.pathsep, spack_root)
# Set an environment variable so that colify will print output like it would to # Set an environment variable so that colify will print output like it would to
# a terminal. # a terminal.
@ -72,8 +73,8 @@
'--no-toc', # Don't create a table of contents file '--no-toc', # Don't create a table of contents file
'--output-dir=.', # Directory to place all output '--output-dir=.', # Directory to place all output
] ]
sphinx_apidoc(apidoc_args + ['../spack']) sphinx_apidoc(apidoc_args + ['_spack_root/lib/spack/spack'])
sphinx_apidoc(apidoc_args + ['../llnl']) sphinx_apidoc(apidoc_args + ['_spack_root/lib/spack/llnl'])
# Enable todo items # Enable todo items
todo_include_todos = True todo_include_todos = True
@ -144,6 +145,13 @@ def setup(sphinx):
# for a list of supported languages. # for a list of supported languages.
#language = None #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 # There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used: # non-false value, then it is used:
#today = '' #today = ''
@ -152,7 +160,7 @@ def setup(sphinx):
# List of patterns, relative to source directory, that match files and # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # 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. # The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None #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 # The name of an image file (relative to this directory) to place at the top
# of the sidebar. # 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 # 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 # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large. # 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, # 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, # 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 see the default settings by looking at
``etc/spack/defaults/config.yaml``: ``etc/spack/defaults/config.yaml``:
.. literalinclude:: ../../../etc/spack/defaults/config.yaml .. literalinclude:: _spack_root/etc/spack/defaults/config.yaml
:language: yaml :language: yaml
These settings can be overridden in ``etc/spack/config.yaml`` or 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 It doesn't take much python coding to get from there to a working
package: package:
.. literalinclude:: ../../../var/spack/repos/builtin/packages/libelf/package.py .. literalinclude:: _spack_root/var/spack/repos/builtin/packages/libelf/package.py
:lines: 6- :lines: 6-
Spack also provides wrapper functions around common commands like 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: 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 :pyobject: R.setup_environment
The ``r`` package also knows which environment variable should be modified The ``r`` package also knows which environment variable should be modified
to make language extensions provided by other packages available, and modifies to make language extensions provided by other packages available, and modifies
it appropriately in the override of the second method: 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 :pyobject: R.setup_dependent_environment
.. _modules-yaml: .. _modules-yaml:
@ -374,7 +374,7 @@ Write a configuration file
The configuration files that control module generation behavior The configuration files that control module generation behavior
are named ``modules.yaml``. The default configuration: are named ``modules.yaml``. The default configuration:
.. literalinclude:: ../../../etc/spack/defaults/modules.yaml .. literalinclude:: _spack_root/etc/spack/defaults/modules.yaml
:language: yaml :language: yaml
activates the hooks to generate ``tcl`` and ``dotkit`` module files and inspects 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 In order to handle this, you can define a ``url_for_version()`` function
like so: 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 :pyobject: Openmpi.url_for_version
With the use of this ``url_for_version()``, Spack knows to download OpenMPI ``2.1.1`` With the use of this ``url_for_version()``, Spack knows to download OpenMPI ``2.1.1``
@ -1565,7 +1565,7 @@ handles ``RPATH``:
.. _pyside-patch: .. _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 :pyobject: PyPyside.patch
:linenos: :linenos:
@ -2027,7 +2027,7 @@ properties to be used by dependents.
The function declaration should look like this: 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 :pyobject: Qt.setup_dependent_environment
:linenos: :linenos:
@ -2047,7 +2047,7 @@ The arguments to this function are:
A good example of using these is in the Python package: 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 :pyobject: Python.setup_dependent_environment
:linenos: :linenos:
@ -2209,7 +2209,7 @@ same way that Python does.
Let's look at Python's activate function: 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 :pyobject: Python.activate
:linenos: :linenos:
@ -2221,7 +2221,7 @@ Python's setuptools.
Deactivate behaves similarly to activate, but it unlinks files: 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 :pyobject: Python.deactivate
:linenos: :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: 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 :pyobject: AutotoolsPackage.configure
:linenos: :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, build system specific helper methods or attributes to provide, for instance,
configure arguments: 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 :pyobject: M4.configure_args
:linenos: :linenos:
@ -2846,7 +2846,7 @@ Shell command functions
Recall the install method from ``libelf``: 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 :pyobject: Libelf.install
:linenos: :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 additional properties on it to help you out. E.g., in mvapich2, you'll
find this: 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 :pyobject: Mvapich2.setup_dependent_package
That code allows the mvapich2 package to associate an ``mpicc`` property 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. 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 :language: python
:emphasize-lines: 33,36,54 :emphasize-lines: 33,36,54
:lines: 30-76,240-248 :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: 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 :language: python
:lines: 14,43-61,70-88 :lines: 14,43-61,70-88
:emphasize-lines: 21,27,34 :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 $ 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 :language: python
:lines: 102-147 :lines: 102-147
:emphasize-lines: 10,18,24,36,37,38,44 :emphasize-lines: 10,18,24,36,37,38,44
@ -694,7 +694,7 @@ at the :code:`PythonPackage` class:
We see the following: We see the following:
.. literalinclude:: ../../../lib/spack/spack/build_systems/python.py .. literalinclude:: _spack_root/lib/spack/spack/build_systems/python.py
:language: python :language: python
:lines: 19,146-357 :lines: 19,146-357
:linenos: :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 $ spack config --scope defaults edit packages
.. literalinclude:: ../../../etc/spack/defaults/packages.yaml .. literalinclude:: _spack_root/etc/spack/defaults/packages.yaml
:language: yaml :language: yaml
@ -829,7 +829,7 @@ running:
$ spack config --scope defaults edit config $ spack config --scope defaults edit config
.. literalinclude:: ../../../etc/spack/defaults/config.yaml .. literalinclude:: _spack_root/etc/spack/defaults/config.yaml
:language: 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 header that identifies the type of module being generated. In the case of
hierarchical module files it's: hierarchical module files it's:
.. literalinclude:: ../../../share/spack/templates/modules/modulefile.lua .. literalinclude:: _spack_root/share/spack/templates/modules/modulefile.lua
:language: jinja :language: jinja
:lines: 1-6 :lines: 1-6
@ -1437,14 +1437,14 @@ that can be overridden or extended by users, if need be.
, delimited by ``{% ... %}``, , delimited by ``{% ... %}``,
are also permitted in the template language: 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 :language: jinja
:lines: 73-88 :lines: 73-88
The locations where Spack looks for templates are specified The locations where Spack looks for templates are specified
in ``config.yaml``: in ``config.yaml``:
.. literalinclude:: ../../../etc/spack/defaults/config.yaml .. literalinclude:: _spack_root/etc/spack/defaults/config.yaml
:language: yaml :language: yaml
:lines: 21-24 :lines: 21-24

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

@ -5,7 +5,7 @@
"""Schema for compilers.yaml configuration file. """Schema for compilers.yaml configuration file.
.. literalinclude:: ../spack/schema/compilers.py .. literalinclude:: _spack_root/lib/spack/spack/schema/compilers.py
:lines: 13- :lines: 13-
""" """

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

@ -5,7 +5,7 @@
"""Schema for config.yaml configuration file. """Schema for config.yaml configuration file.
.. literalinclude:: ../spack/schema/config.py .. literalinclude:: _spack_root/lib/spack/spack/schema/config.py
:lines: 13- :lines: 13-
""" """

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

@ -5,7 +5,7 @@
"""Schema for env.yaml configuration file. """Schema for env.yaml configuration file.
.. literalinclude:: ../spack/schema/env.py .. literalinclude:: _spack_root/lib/spack/spack/schema/env.py
:lines: 36- :lines: 36-
""" """
from llnl.util.lang import union_dicts 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. """Schema for configuration merged into one file.
.. literalinclude:: ../spack/schema/merged.py .. literalinclude:: _spack_root/lib/spack/spack/schema/merged.py
:lines: 39- :lines: 39-
""" """
from llnl.util.lang import union_dicts 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. """Schema for mirrors.yaml configuration file.
.. literalinclude:: ../spack/schema/mirrors.py .. literalinclude:: _spack_root/lib/spack/spack/schema/mirrors.py
:lines: 13- :lines: 13-
""" """

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

@ -5,7 +5,7 @@
"""Schema for modules.yaml configuration file. """Schema for modules.yaml configuration file.
.. literalinclude:: ../spack/schema/modules.py .. literalinclude:: _spack_root/lib/spack/spack/schema/modules.py
:lines: 13- :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. """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- :lines: 32-
""" """

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

@ -5,7 +5,7 @@
"""Schema for packages.yaml configuration files. """Schema for packages.yaml configuration files.
.. literalinclude:: ../spack/schema/packages.py .. literalinclude:: _spack_root/lib/spack/spack/schema/packages.py
:lines: 13- :lines: 13-
""" """

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

@ -5,7 +5,7 @@
"""Schema for projections.yaml configuration file. """Schema for projections.yaml configuration file.
.. literalinclude:: ../spack/schema/projections.py .. literalinclude:: _spack_root/lib/spack/spack/schema/projections.py
:lines: 13- :lines: 13-
""" """

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

@ -5,7 +5,7 @@
"""Schema for repos.yaml configuration file. """Schema for repos.yaml configuration file.
.. literalinclude:: ../spack/schema/repos.py .. literalinclude:: _spack_root/lib/spack/spack/schema/repos.py
:lines: 13- :lines: 13-
""" """

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

@ -5,7 +5,7 @@
"""Schema for Spack spec-set configuration file. """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- :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 """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- :lines: 32-
""" """