Skip to content

Overhaul the BASICS part of the documentation#50932

Merged
tgamblin merged 44 commits intospack:developfrom
alalazo:docs/rework-getting-started
Jul 8, 2025
Merged

Overhaul the BASICS part of the documentation#50932
tgamblin merged 44 commits intospack:developfrom
alalazo:docs/rework-getting-started

Conversation

@alalazo
Copy link
Copy Markdown
Member

@alalazo alalazo commented Jun 24, 2025 •
edited
Loading

The intent is to organize the information and sections we have in a better way, remove outdated content, and add what is missing.

Modifications:

  • Added an INTRODUCTION part, including
    1. The "Feature Overview"
    2. A very short "Getting Started" guide
    3. An explanation of the Spec syntax
    4. Installing Spack prerequisites on linux and macOS
    5. Using Spack on Windows
  • Added a BASIC USAGE part, including
    1. Listing, installing, uninstalling, finding and using packages
    2. Configuring compilers
    3. Using Spack environments with unify:true and a view
  • Added an ADVANCED TOPICS part, including
    1. Toolchains
    2. Auditing configuration and packages
    3. Verifying installations

@spackbot-app spackbot-app bot added core PR affects Spack core functionality documentation Improvements or additions to documentation labels Jun 24, 2025
@alalazo alalazo modified the milestone: v1.0.0 Jun 26, 2025
@alalazo alalazo mentioned this pull request Jun 26, 2025
Closed
@alalazo alalazo marked this pull request as ready for review June 26, 2025 07:07
@alalazo alalazo force-pushed the docs/rework-getting-started branch 2 times, most recently from ebde8d8 to 062365a Compare June 26, 2025 10:15
haampie
haampie reviewed Jun 26, 2025
View reviewed changes
haampie
haampie reviewed Jun 26, 2025
View reviewed changes
haampie
haampie reviewed Jun 26, 2025
View reviewed changes
haampie
haampie reviewed Jun 26, 2025
View reviewed changes
haampie
haampie reviewed Jun 26, 2025
View reviewed changes
haampie
haampie reviewed Jun 26, 2025
View reviewed changes
haampie
haampie reviewed Jun 26, 2025
View reviewed changes
@haampie haampie mentioned this pull request Jun 26, 2025
Merged
@alalazo alalazo mentioned this pull request Jun 26, 2025
Merged
4 tasks
@alalazo alalazo force-pushed the docs/rework-getting-started branch 2 times, most recently from cbe24d2 to 318203e Compare June 27, 2025 05:57
tgamblin
tgamblin requested changes Jun 27, 2025
View reviewed changes
Copy link
Copy Markdown
Member

@tgamblin tgamblin left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't get very far but I have some requests already

@alalazo alalazo force-pushed the docs/rework-getting-started branch from 318203e to 745262d Compare July 2, 2025 13:16
@haampie
Copy link
Copy Markdown
Member

haampie commented Jul 3, 2025 •
edited
Loading

In the spec syntax SVG:

  • no blank before the @
  • add the usual highlighting of the components
  • render a text version first, to help the screen readers and LLMs etc; maybe show spack install <same spec> as a code-block first.
  • remove the "(required)" bit for package name?
  • the repetition of %gcc@14.2.0 is weird as an example...
  • probably do x86_64_v3 instead of x86_64 as an example for a package manager for hpc applications ;)

I would also not use .. tab-set:: for sections, since then you cannot Ctrl-F something easily, you cannot link to them as sections, and it doesn't work in print/pdf. Just use normal subsections.

haampie
haampie reviewed Jul 3, 2025
View reviewed changes
haampie
haampie reviewed Jul 3, 2025
View reviewed changes
haampie
haampie reviewed Jul 3, 2025
View reviewed changes
haampie
haampie reviewed Jul 3, 2025
View reviewed changes
haampie
haampie reviewed Jul 3, 2025
View reviewed changes
haampie
haampie reviewed Jul 3, 2025
View reviewed changes
haampie
haampie reviewed Jul 3, 2025
View reviewed changes
haampie
haampie reviewed Jul 3, 2025
View reviewed changes
alalazo and others added 23 commits July 8, 2025 08:21
@alalazo
Remove "Shell Support" and "GPG Signing"
0c45873 
Both sections are redundant, and outdated

Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Recover GPG key creation and trusting/untrusting
da056e1 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Remove "Bootstrapping clingo"
5986923 
Redundant, since this is covered in the Reference Bootstrapping

Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Extract a Spec Syntax section
cbbd322 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Restructure the index
7c59b35 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Remove outdated parts of Spec Syntax
f7b219d 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Reorder existing topics
6c49e5b 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo @alecbcs
Remove outdated content from "Spack Environment" section
179c8aa 
Co-authored-by: Alec Scott <19558067+alecbcs@users.noreply.github.com>
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Move "Spack Prerequisites" at the end of the introduction
4fb96ae 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Move "Spack On Windows" in the INTRODUCTION
3c23cae 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Tweak details in "Getting Started" section
4a01f6d 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Improve "Spec Syntax"
22b61b5 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Revert "Limit max height of code blocks"
f2c387a 
This reverts commit 48a4df0.
@alalazo
Split "basic_usage" into two files
746035e 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Remove documentation on spack deprecate
d6aff18 
The documentation takes more space on warning the
user that the command should not be used in most
cases, than documenting what it does.

The use case should be completely covered by splicing,
so remove docs for now to avoid advertizing it.

Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
Address review comments for toolchains
dce57c5 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
configuring compilers: apply suggested changes
cb8241f 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
getting_started.rst: apply suggested changes
aee2c65 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
package_fundamentals.rst: apply suggested changes
359cf1d 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
spec_syntax.rst: apply suggested changes
c422869 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
advanced_topics.rst: apply some of the suggested changes
4f98811 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
spec_syntax.rst: implement requested changes
d755339 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo
advanced_topics.rst: reword toolchains
fb4129a 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@alalazo alalazo force-pushed the docs/rework-getting-started branch from efc6e3a to fb4129a Compare July 8, 2025 06:26
@alalazo
Fix missing reference
96c027f 
Signed-off-by: Massimiliano Culpo <massimiliano.culpo@gmail.com>
@tgamblin tgamblin merged commit e80d22b into spack:develop Jul 8, 2025
31 checks passed
@alalazo alalazo deleted the docs/rework-getting-started branch July 8, 2025 13:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@haampie haampie haampie left review comments

@tgamblin tgamblin tgamblin approved these changes

Assignees

@tgamblin tgamblin

Labels

core PR affects Spack core functionality documentation Improvements or additions to documentation

Projects

None yet

Milestone

v1.0.0

Development

Successfully merging this pull request may close these issues.

3 participants

@alalazo @haampie @tgamblin