documentation: added an how-to part before reference docs

[alalazo]

fixes #15848

The idea of the how-to part of the docs is to provide short and clear examples to specific problems that a user may want to solve with Spack. It assumes the user to be already familiar with Spack terminology, to keep each how-to short, but ideally provides a lot of links to reference documentation for people who need to dig deeper in a topic.

Each how-to item has the following structure:

1. Problem: Brief statement of the use case that is going to be solved.
2. Solution: Walkthrough for the current problem.
3. Discussion: Comments on the caveats of the solution being proposed

An example of the current layout is:

Modifications:

• Add some content to the how to part (mainly grabbed from the "Workflows" section under "Basics")
• Move the entire Workflows section under "How to" (is there consensus on this?)
• Add content for the issues linked in Add an "How to" part in the documentation #15848

[alalazo]

@adamjstewart

[adamjstewart]

I'm trying to decide if this belongs as another top-level section. What other guides might we add in the future?

I'm also concerned about possible overlap with other sections. The Workflows section, and in particular "how to replace homebrew/conda with spack" might belong in the How To section. More documentation is always great, but I fear we're getting to the point that the documentation is so long that no one ever reads it.

Another possible thing to add: we get a lot of questions about how to uninstall Spack, either to do a clean upgrade or to stop using Spack altogether. We should add a list of directories to delete ($SPACK_ROOT, /etc/spack, ~/.spack).

[alalazo]

The Workflows section, and in particular "how to replace homebrew/conda with spack" might belong in the How To section.

I believe so too. I grabbed most of the current content from the "Workflows" section and I think, if there's consensus, we should delete the "Workflows" (and prune outdated content). The Conda/Homebrew section is one of the how-to in this draft PR

[tgamblin]

Would this be better labeled as a FAQ? It's a big long for a FAQ. Or should we merge this and workflows? I agree with Adam that we have too many docs. We should really reduce the number of top-level sections, and it might be nice to have some kind of feature overview in the reference docs. Something like this, with workflow-oriented sections, is good but I think it should have lots of links to reference documentation...

[cosmicexplorer]

What other guides might we add in the future?

I think guides for exposing packages in specific languages might be useful. For something like rust with our rust-bindgen package, it's not extremely clear how the rust project should be using bindgen to consume C libraries. I think we should actually have a build system for rust, but until then, a guide that explicitly says "these are spack's current capabilities with rust" seems like it might be useful.

Similarly for R with Rcpp.

[tldahlgren]

I'm trying to decide if this belongs as another top-level section. What other guides might we add in the future?

IMO Having it at the top under Basics is a good place for it. I see this as a section that would provide a bit more information than a FAQ.

Other guides (not volunteering for all):

• How to add Install (or Smoke) tests to an existing package
• How to add CudaPackage and or ROCmPackage to an existing package
• How to convert a custom Package to use a build system (e.g., CMakePackage)
• How to add build- and install-time tests to an existing package (i.e., the call-backs)

[cosmicexplorer]

build- and install-time tests

I agree with the use of the "build-time" and "install-time" nomenclature instead of the current "install tests".

[tldahlgren]

Would this be better labeled as a FAQ?

Could we have a separate FAQ, perhaps between BASICS and HOW TO GUIDES?

I could see a FAQ consisting of single sentence-to-short paragraph answers with pointers to places in the docs that have more information.

[tldahlgren]

build- and install-time tests

I agree with the use of the "build-time" and "install-time" nomenclature instead of the current "install tests".

Install tests are what we've been calling smoke tests -- short tests that can be run days and weeks after the installation -- whereas what I mention here as "build-time" and "install-time" tests are tests that are intended to be run after spack install completes the build and install phases, respectively. The latter are associated with callbacks in one or more of the following build systems:

• Autotools and Makefile (build_time_test_callbacks, install_time_test_callbacks)
• CMake and Meson (build_time_test_callbacks)

[tldahlgren]

build- and install-time tests

I agree with the use of the "build-time" and "install-time" nomenclature instead of the current "install tests".

Install tests are what we've been calling smoke tests -- short tests that can be run days and weeks after the installation -- whereas what I mention here as "build-time" and "install-time" tests are tests that are intended to be run after spack install completes the build and install phases, respectively. The latter are associated with callbacks in one or more of the following build systems:

• Autotools and Makefile (build_time_test_callbacks, install_time_test_callbacks)
• CMake and Meson (build_time_test_callbacks)

I should clarify that those are the test checks that have been uppermost in my mind.

Packages have also added custom build-time tests with different names (e.g., check, check_install, test (to be confused with install/smoke tests ☹️ :),test_install) that may or may not be marked with the run_after directive.

[shahzebsiddiqui]

Would you like me to still work on #22051 or somehow merge these two efforts together

[alalazo]

@tldahlgren @shahzebsiddiqui I'll try to have this ready for review by end of this week. If we decide to merge something like this then we can independently add content once it's merged.

[shahzebsiddiqui]

sounds good @alalazo, once this is merged and i move my section into the same page, i see your section is a How To guide which is more detailed while mine is a FAQ style with short answers. I am not sure if you all prefer these be in one page or two sub-pages. I guess we can discuss that in #22051 once this is merged.

[alalazo]

@adamjstewart

I'm also concerned about possible overlap with other sections. The Workflows section, and in particular "how to replace homebrew/conda with spack" might belong in the How To section. More documentation is always great, but I fear we're getting to the point that the documentation is so long that no one ever reads it

I removed the workflow section entirely, as it has either outdated information or it has been incorporated into the "How to". Your section on Conda is currently "How do I use Spack for single-user installations on my laptop?". Let me know if you have suggestions for more content or better phrasing. There are a couple of points that I may insert back in the How to after having reworked outdated information:

• How to manage filesystem views (but with a focus solely on environments)
• How to upstream patches (much shorter version of what was there before, possibly pointing at Fedora docs which are great in that respect)