Skip to content

Fix sixteen broken relative links in the docs - #3436

Open
kutsibalci wants to merge 1 commit into
NVIDIA:mainfrom
kutsibalci:fix-broken-doc-links
Open

Fix sixteen broken relative links in the docs#3436
kutsibalci wants to merge 1 commit into
NVIDIA:mainfrom
kutsibalci:fix-broken-doc-links

Conversation

@kutsibalci

Copy link
Copy Markdown

Sixteen relative links in the documentation point at paths that are not in the tree. In every case the file being linked to does exist — the link is stale.

I resolved every relative markdown link in media/docs/, examples/, python/ and tools/ against a clone of main. 318 links, 31 unresolved. These are the 16 where the intended target is not a guess; the other 15 are listed at the bottom, untouched.

media/docs/*.md moved under media/docs/cpp/

File Link
examples/59_ampere_gather_scatter_conv/README.md:25 ../../media/docs/implicit_gemm_convolution.md
examples/65_distributed_gemm/REQUIREMENTS.md:7 ../../media/docs/dependent_kernel_launch.md
examples/82_blackwell_distributed_gemm/REQUIREMENTS.md:7 ../../media/docs/dependent_kernel_launch.md

Both targets exist only at media/docs/cpp/…. examples/81_blackwell_gemm_blockwise/README.md:49 — same directory depth — already writes ../../media/docs/cpp/profiler.md, so the corrected form is the one the repository already uses.

blackwell_functionality.md needs three levels, not two

The file sits at media/docs/cpp/, so ../../ lands in media/. Five links leave media/ and therefore never resolve:

-[example](../../examples/79_blackwell_geforce_gemm/)
+[example](../../../examples/79_blackwell_geforce_gemm/)

and the same for ../../test/unit/gemm/device/sm120_tensorop_gemm/ and the three sm120_bs_gemm_*.cu files on lines 664–666.

The two ../../images/… links in the same file on lines 630 and 634 are correct and are not touched — those resolve to media/images/, which is exactly where the images live. This is not a blanket "add one more ../".

Renamed example directories

examples/README.md lists three directories under names they no longer have:

Line Written Actual directory
20 02_dump_reg_smem 02_dump_reg_shmem
176 41_multi_head_attention 41_fused_multi_head_attention
209 49_hopper_gemm_schedules_with_collective_builder 49_hopper_gemm_with_collective_builder

Each has exactly one candidate at that number, and every other entry in the list uses the directory name verbatim, so the label is updated to match as well.

Deprecated notebooks moved next to their README

examples/python/deprecated/README.md links to /examples/python/00_basic_gemm.ipynb and four siblings. All five notebooks are in examples/python/deprecated/, in the same directory as the README, so the links are now plain filenames.

What I did not touch

  • examples/README.md:188 lists 44_fused_multi_head_attention, but directory 44 is 44_multi_gemm_ir_and_codegen — a back-to-back GEMM code generator, not attention. It looks as though the fused MHA example became 41 and this entry was left behind, which would mean rewriting the entry's title and description rather than repointing a link. That is a call for someone who knows the history, so I left it and am flagging it here.
  • media/docs/cpp/code_organization.md:85 links to cute/index. There is a media/docs/cpp/cute/index.rst, so this may be a Sphinx-style reference that is correct in a built site and only looks broken on GitHub. I did not want to change something that might be deliberate.
  • python/CuTeDSL/cutlass/utils/README.md — nine links into ./ and ../examples/… under python/CuTeDSL/cutlass/. Files with those names exist, but under examples/python/CuTeDSL/cute/… with a different structure (block_api vs cute, tutorial_gemm under tutorial), and two of them match more than one candidate. Picking one would be guessing.
  • examples/python/CuTeDSL/experimental/task_scheduling/blackwell/tutorial/README.md — three links to blackwell/kernel/dense_gemm_ts/…, attention_ts/fmha/ and blackwell_geforce/. Those paths are absent from the tree entirely, not moved.
  • python/README.md:131 links to 02_pytorch_extension_grouped_gemm.ipynb, which now exists at two different paths (examples/python/deprecated/ and python/docs/externals/). Ambiguous, so left alone.

A false-positive class worth naming

Links written with a leading slash — /python/cutlass_library, /media/images/… — are not broken. I checked the rendered page rather than assuming: GitHub rewrites them to /NVIDIA/cutlass/blob/main/…. My first pass flagged ten of these; all ten are fine and none is in this PR.

Likewise, sample program output such as ptr[32b](0x7f42efc00000) in cute/03_tensor.md matches the markdown link grammar exactly. Fourteen pointer values were flagged before I excluded code blocks. None is in this PR.

Checks

  • Re-running the sweep after this change: 31 unresolved links become 15, and the 15 are exactly the ones listed above.
  • Each corrected target was confirmed to exist in a clone of main.
  • Documentation only — 6 files, +16/-16, no code, build or test changes.

AI disclosure

AI-assisted (Claude Code). The link resolution and this description were produced with the tool, and I verified the findings before opening: I confirmed each target exists in the tree, checked that a sibling file at the same depth already uses the corrected media/docs/cpp/ form, worked out that only the links leaving media/ in blackwell_functionality.md are wrong while its image links are right, listed the real example directories to confirm each rename had a single candidate, and checked the rendered GitHub page to establish that leading-slash links resolve — which removed ten candidates I would otherwise have reported wrongly. The exclusions above were each looked at individually. I have reviewed and understood the change and take responsibility for it.

Four groups, each with a target that exists in the tree:

- media/docs/*.md now live under media/docs/cpp/, but three examples still
  link to the old location.
- blackwell_functionality.md moved into media/docs/cpp/, so links leaving
  media/ need three levels rather than two. Its ../../images/ links already
  resolve correctly and are left alone.
- Three entries in examples/README.md name a directory that has since been
  renamed.
- The deprecated Python notebooks moved into examples/python/deprecated/
  alongside their README, which still links to their old paths.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant