From 9e54134dafa44a0817a440b3ccf05c46407e7962 Mon Sep 17 00:00:00 2001 From: Todd Gamblin Date: Sat, 30 Sep 2023 20:36:22 -0700 Subject: [PATCH] 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. --- lib/spack/docs/.gitignore | 1 - lib/spack/docs/basic_usage.rst | 5 +- .../docs/build_systems/inteloneapipackage.rst | 4 +- lib/spack/docs/conf.py | 3 -- lib/spack/docs/contribution_guide.rst | 52 ++----------------- lib/spack/docs/index.rst | 10 +++- lib/spack/docs/package_list.rst | 17 ------ lib/spack/docs/replace_conda_homebrew.rst | 24 ++++----- 8 files changed, 30 insertions(+), 86 deletions(-) delete mode 100644 lib/spack/docs/package_list.rst 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 `_ 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 `. +can find a `full list here `_. 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 ``_ 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["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 `. -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,9 +54,16 @@ or refer to the full manual below. features getting_started basic_usage - Tutorial: Spack 101 replace_conda_homebrew +.. toctree:: + :maxdepth: 2 + :caption: Links + + Tutorial (spack-tutorial.rtfd.io) + Packages (packages.spack.io) + Binaries (binaries.spack.io) + .. toctree:: :maxdepth: 2 :caption: Reference @@ -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. --------------