summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorTodd Gamblin <tgamblin@llnl.gov>2023-09-30 20:36:22 -0700
committerGitHub <noreply@github.com>2023-10-01 05:36:22 +0200
commit9e54134dafa44a0817a440b3ccf05c46407e7962 (patch)
treeec0f47940f955fcee83452c6a7c958931d43647f /lib
parent08a9345fccd6c3cb9c574101e9b98abc1e2c4131 (diff)
downloadspack-9e54134dafa44a0817a440b3ccf05c46407e7962.tar.gz
spack-9e54134dafa44a0817a440b3ccf05c46407e7962.tar.bz2
spack-9e54134dafa44a0817a440b3ccf05c46407e7962.tar.xz
spack-9e54134dafa44a0817a440b3ccf05c46407e7962.zip
docs: Replace package list with packages.spack.io (#40251)
For a long time, the docs have generated a huge, static HTML package list. It has some disadvantages: * It's slow to load * It's slow to build * It's hard to search We now have a nice website that can tell us about Spack packages, and it's searchable so users can easily find the one or two packages out of 7400 that they're looking for. We should link to this instead of including a static package list page in the docs. - [x] Replace package list link with link to packages.spack.io - [x] Remove `package_list.html` generation from `conf.py`. - [x] Add a new section for "Links" to the docs. - [x] Remove docstring notes from contribution guide (we haven't generated RST for package docstrings for a while) - [x] Remove referencese to `package-list` from docs.
Diffstat (limited to 'lib')
-rw-r--r--lib/spack/docs/.gitignore1
-rw-r--r--lib/spack/docs/basic_usage.rst5
-rw-r--r--lib/spack/docs/build_systems/inteloneapipackage.rst4
-rw-r--r--lib/spack/docs/conf.py3
-rw-r--r--lib/spack/docs/contribution_guide.rst52
-rw-r--r--lib/spack/docs/index.rst10
-rw-r--r--lib/spack/docs/package_list.rst17
-rw-r--r--lib/spack/docs/replace_conda_homebrew.rst24
8 files changed, 30 insertions, 86 deletions
diff --git a/lib/spack/docs/.gitignore b/lib/spack/docs/.gitignore
index d481aa0923..b349291a8a 100644
--- a/lib/spack/docs/.gitignore
+++ b/lib/spack/docs/.gitignore
@@ -1,4 +1,3 @@
-package_list.html
command_index.rst
spack*.rst
llnl*.rst
diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index af6d2dab91..d1f048ac05 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -45,7 +45,8 @@ Listing available packages
To install software with Spack, you need to know what software is
available. You can see a list of available package names at the
-:ref:`package-list` webpage, or using the ``spack list`` command.
+`packages.spack.io <https://packages.spack.io>`_ website, or
+using the ``spack list`` command.
.. _cmd-spack-list:
@@ -60,7 +61,7 @@ can install:
:ellipsis: 10
There are thousands of them, so we've truncated the output above, but you
-can find a :ref:`full list here <package-list>`.
+can find a `full list here <https://packages.spack.io>`_.
Packages are listed by name in alphabetical order.
A pattern to match with no wildcards, ``*`` or ``?``,
will be treated as though it started and ended with
diff --git a/lib/spack/docs/build_systems/inteloneapipackage.rst b/lib/spack/docs/build_systems/inteloneapipackage.rst
index bd2e370de0..e9fd26690f 100644
--- a/lib/spack/docs/build_systems/inteloneapipackage.rst
+++ b/lib/spack/docs/build_systems/inteloneapipackage.rst
@@ -25,8 +25,8 @@ use Spack to build packages with the tools.
The Spack Python class ``IntelOneapiPackage`` is a base class that is
used by ``IntelOneapiCompilers``, ``IntelOneapiMkl``,
``IntelOneapiTbb`` and other classes to implement the oneAPI
-packages. See the :ref:`package-list` for the full list of available
-oneAPI packages or use::
+packages. Search for ``oneAPI`` at `<packages.spack.io>`_ for the full
+list of available oneAPI packages, or use::
spack list -d oneAPI
diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
index 63ad656cf3..f1bde9c9fb 100644
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -48,9 +48,6 @@ os.environ["PATH"] += "%s%s" % (os.pathsep, os.path.abspath("_spack_root/bin"))
os.environ["COLIFY_SIZE"] = "25x120"
os.environ["COLUMNS"] = "120"
-# Generate full package list if needed
-subprocess.call(["spack", "list", "--format=html", "--update=package_list.html"])
-
# Generate a command index if an update is needed
subprocess.call(
[
diff --git a/lib/spack/docs/contribution_guide.rst b/lib/spack/docs/contribution_guide.rst
index 8933f590d7..ec9234aa46 100644
--- a/lib/spack/docs/contribution_guide.rst
+++ b/lib/spack/docs/contribution_guide.rst
@@ -310,53 +310,11 @@ Once all of the dependencies are installed, you can try building the documentati
$ make clean
$ make
-If you see any warning or error messages, you will have to correct those before
-your PR is accepted.
-
-If you are editing the documentation, you should obviously be running the
-documentation tests. But even if you are simply adding a new package, your
-changes could cause the documentation tests to fail:
-
-.. code-block:: console
-
- package_list.rst:8745: WARNING: Block quote ends without a blank line; unexpected unindent.
-
-At first, this error message will mean nothing to you, since you didn't edit
-that file. Until you look at line 8745 of the file in question:
-
-.. code-block:: rst
-
- Description:
- NetCDF is a set of software libraries and self-describing, machine-
- independent data formats that support the creation, access, and sharing
- of array-oriented scientific data.
-
-Our documentation includes :ref:`a list of all Spack packages <package-list>`.
-If you add a new package, its docstring is added to this page. The problem in
-this case was that the docstring looked like:
-
-.. code-block:: python
-
- class Netcdf(Package):
- """
- NetCDF is a set of software libraries and self-describing,
- machine-independent data formats that support the creation,
- access, and sharing of array-oriented scientific data.
- """
-
-Docstrings cannot start with a newline character, or else Sphinx will complain.
-Instead, they should look like:
-
-.. code-block:: python
-
- class Netcdf(Package):
- """NetCDF is a set of software libraries and self-describing,
- machine-independent data formats that support the creation,
- access, and sharing of array-oriented scientific data."""
-
-Documentation changes can result in much more obfuscated warning messages.
-If you don't understand what they mean, feel free to ask when you submit
-your PR.
+If you see any warning or error messages, you will have to correct those before your PR
+is accepted. If you are editing the documentation, you should be running the
+documentation tests to make sure there are no errors. Documentation changes can result
+in some obfuscated warning messages. If you don't understand what they mean, feel free
+to ask when you submit your PR.
--------
Coverage
diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst
index be4a42045d..0dd27a2444 100644
--- a/lib/spack/docs/index.rst
+++ b/lib/spack/docs/index.rst
@@ -54,11 +54,18 @@ or refer to the full manual below.
features
getting_started
basic_usage
- Tutorial: Spack 101 <https://spack-tutorial.readthedocs.io>
replace_conda_homebrew
.. toctree::
:maxdepth: 2
+ :caption: Links
+
+ Tutorial (spack-tutorial.rtfd.io) <https://spack-tutorial.readthedocs.io>
+ Packages (packages.spack.io) <https://packages.spack.io>
+ Binaries (binaries.spack.io) <https://cache.spack.io>
+
+.. toctree::
+ :maxdepth: 2
:caption: Reference
configuration
@@ -72,7 +79,6 @@ or refer to the full manual below.
repositories
binary_caches
command_index
- package_list
chain
extensions
pipelines
diff --git a/lib/spack/docs/package_list.rst b/lib/spack/docs/package_list.rst
deleted file mode 100644
index dfff070460..0000000000
--- a/lib/spack/docs/package_list.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-.. Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
- Spack Project Developers. See the top-level COPYRIGHT file for details.
-
- SPDX-License-Identifier: (Apache-2.0 OR MIT)
-
-.. _package-list:
-
-============
-Package List
-============
-
-This is a list of things you can install using Spack. It is
-automatically generated based on the packages in this Spack
-version.
-
-.. raw:: html
- :file: package_list.html
diff --git a/lib/spack/docs/replace_conda_homebrew.rst b/lib/spack/docs/replace_conda_homebrew.rst
index 42a3561300..c0d2060c70 100644
--- a/lib/spack/docs/replace_conda_homebrew.rst
+++ b/lib/spack/docs/replace_conda_homebrew.rst
@@ -4,7 +4,7 @@
SPDX-License-Identifier: (Apache-2.0 OR MIT)
=====================================
-Using Spack to Replace Homebrew/Conda
+Spack for Homebrew/Conda Users
=====================================
Spack is an incredibly powerful package manager, designed for supercomputers
@@ -191,18 +191,18 @@ The ``--fresh`` flag tells Spack to use the latest version of every package
where possible instead of trying to optimize for reuse of existing installed
packages.
-The ``--force`` flag in addition tells Spack to overwrite its previous
-concretization decisions, allowing you to choose a new version of Python.
-If any of the new packages like Bash are already installed, ``spack install``
+The ``--force`` flag in addition tells Spack to overwrite its previous
+concretization decisions, allowing you to choose a new version of Python.
+If any of the new packages like Bash are already installed, ``spack install``
won't re-install them, it will keep the symlinks in place.
-----------------------------------
Updating & Cleaning Up Old Packages
-----------------------------------
-If you're looking to mimic the behavior of Homebrew, you may also want to
-clean up out-of-date packages from your environment after an upgrade. To
-upgrade your entire software stack within an environment and clean up old
+If you're looking to mimic the behavior of Homebrew, you may also want to
+clean up out-of-date packages from your environment after an upgrade. To
+upgrade your entire software stack within an environment and clean up old
package versions, simply run the following commands:
.. code-block:: console
@@ -212,9 +212,9 @@ package versions, simply run the following commands:
$ spack concretize --fresh --force
$ spack install
$ spack gc
-
-Running ``spack mark -i --all`` tells Spack to mark all of the existing
-packages within an environment as "implicitly" installed. This tells
+
+Running ``spack mark -i --all`` tells Spack to mark all of the existing
+packages within an environment as "implicitly" installed. This tells
spack's garbage collection system that these packages should be cleaned up.
Don't worry however, this will not remove your entire environment.
@@ -223,8 +223,8 @@ a fresh concretization and will re-mark any packages that should remain
installed as "explicitly" installed.
**Note:** if you use multiple spack environments you should re-run ``spack install``
-in each of your environments prior to running ``spack gc`` to prevent spack
-from uninstalling any shared packages that are no longer required by the
+in each of your environments prior to running ``spack gc`` to prevent spack
+from uninstalling any shared packages that are no longer required by the
environment you just upgraded.
--------------