toolkit: install guide: refer to section about supported platforms, tweak headings #158

jgehrcke · 2025-02-13T13:03:23Z

I find it important that the installation section informs about supported platforms. We have a section for that (in a different doc) so all we are missing is a cross-reference.

Is Sphinx our documentation generator? I think / hope that cross-references in md-sphinx work as I am trying here, but I did not test this locally.

Also tweaking the headings to shift attention to the distribution names more than the tooling.

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

github-actions · 2025-02-13T13:06:38Z

Documentation preview

https://nvidia.github.io/cloud-native-docs/review/pr-158

jgehrcke · 2025-02-13T13:25:55Z

Sweeet! 🎈

Artifact html-build-artifact.zip successfully finalized. Artifact ID 2585643272
Artifact html-build-artifact has been successfully uploaded! Final size is 34511668 bytes. Artifact ID is 2585643272
Artifact download URL: https://github.com/NVIDIA/cloud-native-docs/actions/runs/13308323093/artifacts/2585643272

Looking at that.

Edit: the cross ref is correct, the anchor works.

Screenshot, FYI:

elezar · 2025-02-13T13:55:53Z

container-toolkit/install-guide.md


-Alternatively, you can install the driver by downloading a `.run` installer.
-Refer to the NVIDIA [Official Drivers](https://www.nvidia.com/Download/index.aspx?lang=en-us) page.
+2. Read [this section](./supported-platforms.md) about platform support.


Nit: Should this be first?

+1 i think it should be first as well

and an additional nit to embed the text into the link, so something like
Make sure you are using a [supported platform](./supported-platforms.md).

Nit: Should this be first?

Yes, I was hoping for that feedback!

something like Make sure you are using a supported platform.

In general I like this approach. Here I opted for a subtly different approach because:

It's really a section about platform support in general, and we precisely now want to be mindful to not communicate something in the lines of "do not continue if you do not use a strictly supported platform" :).

Related: #62 and e.g. NVIDIA/nvidia-container-toolkit#482 (comment).

elezar · 2025-02-13T13:56:21Z

container-toolkit/install-guide.md

+2. Read [this section](./supported-platforms.md) about platform support.

-### Installing with Apt
+### Debian-based distributions (Ubuntu):


Does this read as if we're only targetting Ubuntu?

Suggested change

### Debian-based distributions (Ubuntu):

### Debian-based distributions (e.g. Ubuntu):

Right, I forgot to add ", ..." like I did below. In this case I think I like this a little better than "e.g."

Now I have clarity: we don't need generic enumerations. In these headings, we want to make sure we list all those distros that are in the table of "supported platforms". That's all we need. Pushed a commit.

elezar · 2025-02-13T13:56:36Z

container-toolkit/install-guide.md

   ```

-### Installing with Yum or Dnf
+### RPM-based distributions (RHEL/CentOS, Fedora, Amazon Linux, ...):


Suggested change

### RPM-based distributions (RHEL/CentOS, Fedora, Amazon Linux, ...):

### RPM-based distributions (e.g. RHEL/CentOS, Fedora, Amazon Linux, ...):

I started to overthink this. Removed the "RPM-based distributions" again.

Pushed a new commit, let's see how this looks when its rendered! :) I like to first-class the distribution names instead of the tooling names (that was my main angle here). There's no perfect solution though.

Some inspiration from..

chrome

vscode

gcloud cli

signal

elezar · 2025-02-13T13:57:37Z

container-toolkit/install-guide.md

   ```

-### Installing with Zypper
+### OpenSUSE/SLE:


It's a little strange that this is also RPM-based but has its own section. Should we call that out above or have subsections for the two package manager types?

Yes you have a strong point here. Will think about that.

Happy with the current state: https://nvidia.github.io/cloud-native-docs/review/pr-158/container-toolkit/latest/install-guide.html.

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

elezar · 2025-02-14T09:14:10Z

container-toolkit/install-guide.md

-Refer to the NVIDIA [Official Drivers](https://www.nvidia.com/Download/index.aspx?lang=en-us) page.

-### Installing with Apt
+### Ubuntu and Debian


I'm happy with this change for ubuntu and debian since I think this covers most users of apt. My concern is that using the same construct for RPM-based distributions where there are other prominent ones that are not listed. (Rocky comes to mind). This will definitely lead to GitHub issues along the lines of "RockyLinux support when?". At present my response is to link the "Installing with Yum or Dnf" section, but I can see more questions being raised if I link a section that's titled "RHEL/CentOS, Fedora, Amazon Linux".

yes. note: added a commit after working on this with Evan

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

jgehrcke · 2025-02-14T13:55:58Z

Pushed more commits after iterating on this with Evan. Will want to double-check the next rendered version before merge. Will report back.

jgehrcke · 2025-02-14T14:08:28Z

Good: the legacy anchors now work. Example: https://nvidia.github.io/cloud-native-docs/review/pr-158/container-toolkit/latest/install-guide.html#installing-with-apt

elezar

I'm happy with these. Thanks @jgehrcke

a-mccarthy · 2025-02-19T02:08:26Z

container-toolkit/install-guide.md

+Alternatively, you can install the driver by [downloading](https://www.nvidia.com/en-us/drivers/) a `.run` installer.

-Alternatively, you can install the driver by downloading a `.run` installer.
-Refer to the NVIDIA [Official Drivers](https://www.nvidia.com/Download/index.aspx?lang=en-us) page.


Is there a reason why we got ride of this link? I dont remember if this has come up before in a previous comments. thanks

No removal. I replaced it with a more modern URL. You will notice in your browser that the old URL redirects to /en-us/drivers.

Personally, I like to look at changes like this in the rendered view.

We should also work towards using a concept often called "semantic line breaks" to keep the markdown source diff better reviewable.

jgehrcke · 2025-02-19T09:01:15Z

Thanks for discussion, let's certainly iterate more soon!

jgehrcke added 2 commits February 13, 2025 13:58

Tweak headings in toolkit install guide

8316505

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

Refer to supported platforms section in toolkit install guide

550b98a

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

elezar reviewed Feb 13, 2025

View reviewed changes

jgehrcke added 2 commits February 13, 2025 18:01

review feedback: work on section headings

c85c37c

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

simplify

3b8d4df

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

elezar reviewed Feb 14, 2025

View reviewed changes

jgehrcke added 3 commits February 14, 2025 13:33

collab with evan: headings, notes

06bd2b8

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

use legacy heading anchors

ad56540

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

remove todo

cd38c8b

Signed-off-by: Dr. Jan-Philip Gehrcke <[email protected]>

elezar approved these changes Feb 18, 2025

View reviewed changes

a-mccarthy reviewed Feb 19, 2025

View reviewed changes

jgehrcke merged commit 0de48ff into NVIDIA:main Feb 19, 2025
2 checks passed

	### Debian-based distributions (Ubuntu):
	### Debian-based distributions (e.g. Ubuntu):

	### RPM-based distributions (RHEL/CentOS, Fedora, Amazon Linux, ...):
	### RPM-based distributions (e.g. RHEL/CentOS, Fedora, Amazon Linux, ...):

toolkit: install guide: refer to section about supported platforms, tweak headings #158

toolkit: install guide: refer to section about supported platforms, tweak headings #158

Uh oh!

Conversation

jgehrcke commented Feb 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Feb 13, 2025

Documentation preview

Uh oh!

jgehrcke commented Feb 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jgehrcke Feb 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

chrome

vscode

gcloud cli

signal

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jgehrcke commented Feb 14, 2025

Uh oh!

jgehrcke commented Feb 14, 2025

Uh oh!

elezar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jgehrcke Feb 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jgehrcke commented Feb 19, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jgehrcke commented Feb 13, 2025 •

edited

Loading

jgehrcke commented Feb 13, 2025 •

edited

Loading

jgehrcke Feb 13, 2025 •

edited

Loading

jgehrcke Feb 19, 2025 •

edited

Loading