From 69c4043656b86cc9e8f26ce213ec2c6ada8ad3bd Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Sun, 3 Aug 2025 09:22:31 -0700 Subject: [PATCH 1/7] docs: update to furo theme to match Spack docs --- _pygments/style.py | 11 -- _static/css/custom.css | 41 ++++++++ _templates/base.html | 16 +++ _templates/sidebar/brand.html | 23 +++++ conf.py | 183 +++++++++++++++++----------------- requirements.txt | 2 +- 6 files changed, 174 insertions(+), 102 deletions(-) delete mode 100644 _pygments/style.py create mode 100644 _templates/base.html create mode 100644 _templates/sidebar/brand.html diff --git a/_pygments/style.py b/_pygments/style.py deleted file mode 100644 index 32d1ea5c9e..0000000000 --- a/_pygments/style.py +++ /dev/null @@ -1,11 +0,0 @@ -# The name of the Pygments (syntax highlighting) style to use. -# We use our own extension of the default style with a few modifications -from pygments.styles.default import DefaultStyle -from pygments.token import Generic - - -class SpackStyle(DefaultStyle): - styles = DefaultStyle.styles.copy() - background_color = "#f4f4f8" - styles[Generic.Output] = "#355" - styles[Generic.Prompt] = "bold #346ec9" diff --git a/_static/css/custom.css b/_static/css/custom.css index be015f8306..091c2fffb5 100644 --- a/_static/css/custom.css +++ b/_static/css/custom.css @@ -2,3 +2,44 @@ overflow-y: auto; max-height: 700px; } + +div.versionadded { + border-left: 3px solid #0c731f; + color: #0c731f; + padding-left: 1rem; +} + +.py.property { + display: block !important; +} + +div.version-switch { + text-align: center; + min-height: 2em; +} + +div.version-switch>select { + display: inline-block; + text-align-last: center; + background: none; + border: none; + border-radius: 0.5em; + box-shadow: none; + color: var(--color-foreground-primary); + cursor: pointer; + appearance: none; + padding: 0.2em; + -webkit-appearance: none; + -moz-appearance: none; +} + +div.version-switch select:active, +div.version-switch select:focus, +div.version-switch select:hover { + color: var(--color-foreground-secondary); + background: var(--color-background-hover); +} + +.toc-tree li.scroll-current>.reference { + font-weight: normal; +} diff --git a/_templates/base.html b/_templates/base.html new file mode 100644 index 0000000000..2badf3be1d --- /dev/null +++ b/_templates/base.html @@ -0,0 +1,16 @@ +{% extends "!base.html" %} + +{%- block extrahead %} + + + + {%- if READTHEDOCS %} + + + {%- endif %} +{% endblock %} diff --git a/_templates/sidebar/brand.html b/_templates/sidebar/brand.html new file mode 100644 index 0000000000..ee32c92ead --- /dev/null +++ b/_templates/sidebar/brand.html @@ -0,0 +1,23 @@ + + +{%- if READTHEDOCS %} +
+{%- endif %} diff --git a/conf.py b/conf.py index 6196a83f4c..b3115c6647 100644 --- a/conf.py +++ b/conf.py @@ -22,12 +22,12 @@ # -- Spack customizations ----------------------------------------------------- # Add the Spack bin directory to the path so that we can use its output in docs. -os.environ['SPACK_ROOT'] = os.path.abspath('_spack_root') -os.environ['PATH'] += f"{os.pathsep}{os.path.abspath('_spack_root/bin')}" +os.environ["SPACK_ROOT"] = os.path.abspath("_spack_root") +os.environ["PATH"] += f"{os.pathsep}{os.path.abspath('_spack_root/bin')}" # Set an environment variable so that colify will print output like it would to a terminal. -os.environ['COLIFY_SIZE'] = '25x120' -os.environ['COLUMNS'] = '120' +os.environ["COLIFY_SIZE"] = "25x120" +os.environ["COLUMNS"] = "120" # Enable todo items todo_include_todos = True @@ -38,10 +38,11 @@ # class PatchedPythonDomain(PythonDomain): def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): - if 'refspecific' in node: - del node['refspecific'] + if "refspecific" in node: + del node["refspecific"] return super(PatchedPythonDomain, self).resolve_xref( - env, fromdocname, builder, typ, target, node, contnode) + env, fromdocname, builder, typ, target, node, contnode + ) def setup(sphinx): @@ -50,56 +51,60 @@ def setup(sphinx): # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.8' +needs_sphinx = "1.8" # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = [ - 'sphinx.ext.graphviz', - 'sphinx.ext.todo', - 'sphinx_copybutton', + "sphinx.ext.graphviz", + "sphinx.ext.todo", + "sphinx_copybutton", ] # Set default graphviz options graphviz_dot_args = [ - '-Grankdir=LR', '-Gbgcolor=transparent', - '-Nshape=box', '-Nfontname=monaco', '-Nfontsize=10'] + "-Grankdir=LR", + "-Gbgcolor=transparent", + "-Nshape=box", + "-Nfontname=monaco", + "-Nfontsize=10", +] # Get nice vector graphics graphviz_output_format = "svg" # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ".rst" # The encoding of source files. -source_encoding = 'utf-8-sig' +source_encoding = "utf-8-sig" # The master toctree document. -master_doc = 'index' +master_doc = "index" # General information about the project. -project = u'Spack Tutorial' -copyright = u'Spack Project Developers' +project = "Spack Tutorial" +copyright = "Spack Project Developers" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -#import spack -#version = '.'.join(str(s) for s in spack.spack_version_info[:2]) +# import spack +# version = '.'.join(str(s) for s in spack.spack_version_info[:2]) # The full version, including alpha/beta/rc tags. -#release = spack.spack_version +# release = spack.spack_version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# language = None # Places to look for .po/.mo files for doc translations -#locale_dirs = [] +# locale_dirs = [] # Sphinx gettext settings gettext_compact = True @@ -107,174 +112,166 @@ def setup(sphinx): # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', '_spack_root', 'view', '._view'] +exclude_patterns = ["_build", "_spack_root", "view", "._view"] # The reST default role (used for this markup: `text`) to use for all documents. -#default_role = None +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. -# We use our own extension of the default style with a few modifications -sys.path.append('./_pygments') # make 'conf' module findable -pygments_style = 'style.SpackStyle' +# show_authors = False # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # -- Options for HTML output --------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -html_theme_options = { 'logo_only' : True } +html_theme = "furo" # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = ["_themes"] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +# html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -html_logo = '_spack_root/share/spack/logo/spack-logo-white-text.svg' +html_theme_options = { + "sidebar_hide_name": True, + "light_logo": "spack-logo-text.svg", + "dark_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 = '_spack_root/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, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] # These paths are either relative to html_static_path html_css_files = [ - 'css/custom.css', + "css/custom.css", ] +html_context = {} + +if os.environ.get("READTHEDOCS", "") == "True": + html_context["READTHEDOCS"] = True # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -html_last_updated_fmt = '%b %d, %Y' +html_last_updated_fmt = "%b %d, %Y" # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = False +# html_show_sphinx = False # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'Spackdoc' +htmlhelp_basename = "Spackdoc" # -- Options for LaTeX output -------------------------------------------------- latex_elements = { -# The paper size ('letterpaper' or 'a4paper'). -#'papersize': 'letterpaper', - -# The font size ('10pt', '11pt' or '12pt'). -#'pointsize': '10pt', - -# Additional stuff for the LaTeX preamble. -#'preamble': '', + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'Spack.tex', u'Spack Documentation', - u'Todd Gamblin', 'manual'), + ("index", "Spack.tex", "Spack Documentation", "Todd Gamblin", "manual"), ] # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True # -- Options for manual page output -------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'spack', u'Spack Documentation', - [u'Todd Gamblin'], 1) -] +man_pages = [("index", "spack", "Spack Documentation", ["Todd Gamblin"], 1)] # If true, show URL addresses after external links. -#man_show_urls = False +# man_show_urls = False # -- Options for Texinfo output ------------------------------------------------ @@ -283,22 +280,28 @@ def setup(sphinx): # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'Spack', u'Spack Documentation', - u'Todd Gamblin', 'Spack', 'One line description of project.', - 'Miscellaneous'), + ( + "index", + "Spack", + "Spack Documentation", + "Todd Gamblin", + "Spack", + "One line description of project.", + "Miscellaneous", + ), ] # Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# texinfo_appendices = [] # If false, no module index is generated. -#texinfo_domain_indices = True +# texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# texinfo_show_urls = 'footnote' copybutton_only_copy_prompt_lines = True copybutton_prompt_text = r"$" -copybutton_exclude = '.linenos' +copybutton_exclude = ".linenos" copybutton_copy_empty_lines = False diff --git a/requirements.txt b/requirements.txt index 2aa6703f4d..0b5ed4b364 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,7 +2,7 @@ # to build the documentation. Sphinx==8.2.3 sphinxcontrib-programoutput==0.18 -sphinx-rtd-theme==3.0.2 +furo==2025.7.19 sphinx-copybutton==0.5.2 python-levenshtein==0.27.1 docutils==0.20.1 From e8c575c6f0f7f92516a71fb4004a8d8f6723822c Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Sun, 3 Aug 2025 09:32:22 -0700 Subject: [PATCH 2/7] Add logos --- _static/images/spack-logo-text.svg | 64 ++++++++++++++++++++++++ _static/images/spack-logo-white-text.svg | 64 ++++++++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 _static/images/spack-logo-text.svg create mode 100644 _static/images/spack-logo-white-text.svg diff --git a/_static/images/spack-logo-text.svg b/_static/images/spack-logo-text.svg new file mode 100644 index 0000000000..5ad4588d8a --- /dev/null +++ b/_static/images/spack-logo-text.svg @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/_static/images/spack-logo-white-text.svg b/_static/images/spack-logo-white-text.svg new file mode 100644 index 0000000000..d3dfd73f5c --- /dev/null +++ b/_static/images/spack-logo-white-text.svg @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From dfeaf1976b21ee5f1e59b585f4bc0fc1888cf48a Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Sun, 3 Aug 2025 09:38:49 -0700 Subject: [PATCH 3/7] Fix images location and add versions.js --- _static/js/versions.js | 37 +++++++++++++++++++++++++++++++++++++ conf.py | 4 ++-- 2 files changed, 39 insertions(+), 2 deletions(-) create mode 100644 _static/js/versions.js diff --git a/_static/js/versions.js b/_static/js/versions.js new file mode 100644 index 0000000000..67711d95e9 --- /dev/null +++ b/_static/js/versions.js @@ -0,0 +1,37 @@ +// taken from https://github.com/readthedocs/sphinx_rtd_theme/blob/3.0.2/sphinx_rtd_theme/static/js/versions.js_t + +function onSelectorSwitch(event) { + const option = event.target.selectedIndex; + const item = event.target.options[option]; + window.location.href = item.dataset.url; +} + +document.addEventListener("readthedocs-addons-data-ready", function (event) { + const config = event.detail.data(); + + const versionSwitch = document.querySelector( + "div.version-switch", + ); + let versions = config.versions.active; + if (config.versions.current.hidden || config.versions.current.type === "external") { + versions.unshift(config.versions.current); + } + const versionSelect = ` + +`; + + versionSwitch.innerHTML = versionSelect; + versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch); +}) diff --git a/conf.py b/conf.py index b3115c6647..89162683e9 100644 --- a/conf.py +++ b/conf.py @@ -158,8 +158,8 @@ def setup(sphinx): # of the sidebar. html_theme_options = { "sidebar_hide_name": True, - "light_logo": "spack-logo-text.svg", - "dark_logo": "spack-logo-white-text.svg", + "light_logo": "images/spack-logo-text.svg", + "dark_logo": "images/spack-logo-white-text.svg", } # The name of an image file (within the static path) to use as favicon of the From 0b1b7568a8169db17a831d19a6c7f2b7039a97a7 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Mon, 4 Aug 2025 10:01:56 -0700 Subject: [PATCH 4/7] Fix block quotes for sections --- index.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/index.rst b/index.rst index dc42ff9cfc..be2a8a15dc 100644 --- a/index.rst +++ b/index.rst @@ -53,20 +53,20 @@ You can invoke to start using the container. You should now be ready to run through our demo scripts: - #. :ref:`basics-tutorial` - #. :ref:`environments-tutorial` - #. :ref:`configs-tutorial` - #. :ref:`packaging-tutorial` - #. :ref:`stacks-tutorial` - #. :ref:`developer-workflows-tutorial` - #. :ref:`binary-cache-tutorial` - #. :ref:`spack-scripting-tutorial` +#. :ref:`basics-tutorial` +#. :ref:`environments-tutorial` +#. :ref:`configs-tutorial` +#. :ref:`packaging-tutorial` +#. :ref:`stacks-tutorial` +#. :ref:`developer-workflows-tutorial` +#. :ref:`binary-cache-tutorial` +#. :ref:`spack-scripting-tutorial` Other sections from past tutorials are also available, although they may not be kept up-to-date as frequently: - #. :ref:`modules-tutorial` - #. :ref:`build-systems-tutorial` - #. :ref:`advanced-packaging-tutorial` +#. :ref:`modules-tutorial` +#. :ref:`build-systems-tutorial` +#. :ref:`advanced-packaging-tutorial` Full contents: From 3ecb9ab74f381a799e5823cc574c963c8da945d6 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Mon, 4 Aug 2025 10:14:09 -0700 Subject: [PATCH 5/7] Fix more block quotes --- tutorial_binary_cache.rst | 4 +-- tutorial_buildsystems.rst | 6 ++--- tutorial_developer_workflows.rst | 46 ++++++++++++++++---------------- tutorial_modules.rst | 8 +++--- 4 files changed, 32 insertions(+), 32 deletions(-) diff --git a/tutorial_binary_cache.rst b/tutorial_binary_cache.rst index 6e70e2aaef..5531401c3b 100644 --- a/tutorial_binary_cache.rst +++ b/tutorial_binary_cache.rst @@ -116,9 +116,9 @@ look very similar to a container image --- we will get to that in a bit. You can change the visibility to ``public`` by going to GitHub Packages from your GitHub account, selecting the ``buildcache`` package, go to ``package settings``, and change the visibility to ``public`` in the ``Danger Zone`` section. This page can also be directly accessed by going to - .. code-block:: text + .. code-block:: text - https://github.com/users//packages/container/buildcache/settings + https://github.com/users//packages/container/buildcache/settings ------------------------------- diff --git a/tutorial_buildsystems.rst b/tutorial_buildsystems.rst index aa6268d458..5210895723 100644 --- a/tutorial_buildsystems.rst +++ b/tutorial_buildsystems.rst @@ -163,9 +163,9 @@ These packages are handled by the ``MakefilePackage`` subclass which provides co A ``MakefilePackage`` build has three phases that can be overridden by the packager: - 1. ``edit()`` - 2. ``build()`` - 3. ``install()`` +1. ``edit()`` +2. ``build()`` +3. ``install()`` Packagers then have the ability to control how a ``Makefile`` is edited, and what targets to include for the build phase or install phase. diff --git a/tutorial_developer_workflows.rst b/tutorial_developer_workflows.rst index 3954a61183..9eb9e4f5cc 100644 --- a/tutorial_developer_workflows.rst +++ b/tutorial_developer_workflows.rst @@ -285,22 +285,22 @@ This command is particularly useful in developer environments—it allows develo The additional features of the install command are unnecessary when tightly iterating between building and testing a particular package. For example, the workflow modifying ``scr`` that we just went through can be simplified to: - .. code-block:: console - - $ spack build-env scr -- bash - # Shell wrappers didn't propagate to the subshell - $ source $SPACK_ROOT/share/spack/setup-env.sh - # Lets look at navigation features - $ spack cd --help - $ spack cd -c scr - $ touch src/scr_copy.c - $ spack cd -b scr - # Lets look at whats here - $ ls - # Build and run tests - $ make -j2 - $ make test - $ exit +.. code-block:: console + + $ spack build-env scr -- bash + # Shell wrappers didn't propagate to the subshell + $ source $SPACK_ROOT/share/spack/setup-env.sh + # Lets look at navigation features + $ spack cd --help + $ spack cd -c scr + $ touch src/scr_copy.c + $ spack cd -b scr + # Lets look at whats here + $ ls + # Build and run tests + $ make -j2 + $ make test + $ exit Working with the build environment and along with Spack navigation features provides a nice way to iterate quickly and navigate through the hash-heavy Spack directory structures. @@ -314,13 +314,13 @@ Developers can achieve builds of both cases from a single ``spack install`` as l .. code-block:: console - # First we have to allow repeat specs in the environment - $ spack config add concretizer:unify:false - # Next we need to specify the specs we want ('==' propagates the variant to deps) - $ spack change macsio build_type==Release - $ spack add macsio+scr build_type==Debug - # Inspect the graph for multiple dev_path= - $ spack concretize -f + # First we have to allow repeat specs in the environment + $ spack config add concretizer:unify:false + # Next we need to specify the specs we want ('==' propagates the variant to deps) + $ spack change macsio build_type==Release + $ spack add macsio+scr build_type==Debug + # Inspect the graph for multiple dev_path= + $ spack concretize -f While we won't build out this example it illustrates how the ``dev_path`` for ``build_type=Release`` and ``build_type=Debug`` points to the same source code. diff --git a/tutorial_modules.rst b/tutorial_modules.rst index 7442f71232..24e8b955a3 100644 --- a/tutorial_modules.rst +++ b/tutorial_modules.rst @@ -15,10 +15,10 @@ Both hierarchical and non-hierarchical deployments will be discussed in detail a At the end of the tutorial readers should have a clear understanding of: - * What module files are and how they are used on HPC clusters - * How Spack generates module files for the software it installs - * Which Spack commands can be used to manage module files - * How module files generated by Spack can be customized +* What module files are and how they are used on HPC clusters +* How Spack generates module files for the software it installs +* Which Spack commands can be used to manage module files +* How module files generated by Spack can be customized and be confident that Spack can deal with all of the common use cases that occur when maintaining software installations on HPC clusters. From 77d0454ece373dc2ac20affe823856e974fe5764 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Mon, 4 Aug 2025 12:28:31 -0700 Subject: [PATCH 6/7] Fix more block quotes --- tutorial_modules.rst | 14 +++++++------- tutorial_stacks.rst | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/tutorial_modules.rst b/tutorial_modules.rst index 24e8b955a3..0a827764c3 100644 --- a/tutorial_modules.rst +++ b/tutorial_modules.rst @@ -634,8 +634,8 @@ This layout is quite simple to deploy, but you can see from the above snippet th Even if ``conflicts`` directives are carefully placed in module files, they: - - won't enforce a consistent environment, but will just report an error - - need constant updates, for instance as soon as a new compiler or MPI library is installed +- won't enforce a consistent environment, but will just report an error +- need constant updates, for instance as soon as a new compiler or MPI library is installed `Hierarchical module files `_ try to overcome these shortcomings by showing at start-up only a restricted view of what is available on the system: more specifically, only the software that has been installed with OS provided compilers. Among this software, there will be other -- usually more recent -- compilers that, once loaded, will prepend new directories to ``MODULEPATH``, unlocking all the software that was compiled with them. @@ -648,11 +648,11 @@ Core/Compiler/MPI The most widely used hierarchy is the so called ``Core/Compiler/MPI`` where, on top of the compilers, different MPI libraries also unlock software linked to them. There are just a few steps needed to adapt the ``modules.yaml`` file we used previously: - #. enable the ``lmod`` file generator - #. change the ``tcl`` tag to ``lmod`` - #. remove the ``tcl`` specific ``conflict`` directive - #. declare which compilers are considered ``core_compilers`` - #. remove the ``mpi`` related suffixes in projections (as they will be substituted by hierarchies) +#. enable the ``lmod`` file generator +#. change the ``tcl`` tag to ``lmod`` +#. remove the ``tcl`` specific ``conflict`` directive +#. declare which compilers are considered ``core_compilers`` +#. remove the ``mpi`` related suffixes in projections (as they will be substituted by hierarchies) After these modifications your configuration file should look like: diff --git a/tutorial_stacks.rst b/tutorial_stacks.rst index 42c3b514ec..27fd72f9d2 100644 --- a/tutorial_stacks.rst +++ b/tutorial_stacks.rst @@ -39,8 +39,8 @@ Setup the compiler The first step to build our stack is to setup the compiler we want to use later. This is currently an iterative process that can be done in two ways: - 1. Install the compiler first, then register it in the environment - 2. Use a second environment just for the compiler +1. Install the compiler first, then register it in the environment +2. Use a second environment just for the compiler Below, we'll use the first approach. For people interested, an example of the latter approach can be found `at this link `_. From cbb9d06593e22948739b77945d8fb0a78eec52f3 Mon Sep 17 00:00:00 2001 From: Alec Scott Date: Mon, 4 Aug 2025 13:32:05 -0700 Subject: [PATCH 7/7] docs: fix indentation --- tutorial_developer_workflows.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tutorial_developer_workflows.rst b/tutorial_developer_workflows.rst index 9eb9e4f5cc..c1748ab3b5 100644 --- a/tutorial_developer_workflows.rst +++ b/tutorial_developer_workflows.rst @@ -314,13 +314,13 @@ Developers can achieve builds of both cases from a single ``spack install`` as l .. code-block:: console - # First we have to allow repeat specs in the environment - $ spack config add concretizer:unify:false - # Next we need to specify the specs we want ('==' propagates the variant to deps) - $ spack change macsio build_type==Release - $ spack add macsio+scr build_type==Debug - # Inspect the graph for multiple dev_path= - $ spack concretize -f + # First we have to allow repeat specs in the environment + $ spack config add concretizer:unify:false + # Next we need to specify the specs we want ('==' propagates the variant to deps) + $ spack change macsio build_type==Release + $ spack add macsio+scr build_type==Debug + # Inspect the graph for multiple dev_path= + $ spack concretize -f While we won't build out this example it illustrates how the ``dev_path`` for ``build_type=Release`` and ``build_type=Debug`` points to the same source code.