+ {%- endif %}
+ {% if not theme_sidebar_hide_name %}
+ {{ docstitle if docstitle else project }}
+ {%- endif %}
+ {% endblock brand_content %}
+
+
+{%- if READTHEDOCS %}
+
+{%- endif %}
diff --git a/conf.py b/conf.py
index 6196a83f4c..89162683e9 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": "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
# 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/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:
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
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..c1748ab3b5 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.
diff --git a/tutorial_modules.rst b/tutorial_modules.rst
index 7442f71232..0a827764c3 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.
@@ -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 `_.
+  }})
+  }})
+