[all-commits] [llvm/llvm-project] f7d9d0: [doc] Address various sphinx warnings (nearly NFC)

[Scott Linder via All-commits]

  Branch: refs/heads/users/slinder1/Icb11de69be1ea5489fba501aee4d767f5129e7e1
  Home:   https://github.com/llvm/llvm-project
  Commit: f7d9d0cb018b6d732af19a16c5a074eaa592be99
      https://github.com/llvm/llvm-project/commit/f7d9d0cb018b6d732af19a16c5a074eaa592be99
  Author: Scott Linder <Scott.Linder at amd.com>
  Date:   2026-06-05 (Fri, 05 Jun 2026)

  Changed paths:
    M llvm/docs/CommandGuide/index.rst
    M llvm/docs/GettingInvolved.rst
    M llvm/docs/GlobalISel/Pipeline.rst
    M llvm/docs/GlobalISel/Porting.rst
    M llvm/docs/GlobalISel/index.rst
    M llvm/docs/Reference.rst
    M llvm/docs/UserGuides.rst
    M llvm/docs/tutorial/MyFirstLanguageFrontend/index.rst
    M llvm/tools/llvm-debuginfo-analyzer/README.md

  Log Message:
  -----------
  [doc] Address various sphinx warnings (nearly NFC)

It seems like using a non-`hidden` `toctree` for page navigation is a
bit of a trap, in that every doc must have a single unique path through
the global TOC tree to the root doc, and it is very easy to end up with
multiple.

This patch tries to address the warnings in llvm/docs/, namely:

  $ sphinx-build -b html -jauto llvm/docs/ /tmp/sphinx-out
  checking consistency...
  llvm/docs/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack.md: document is referenced in multiple toctrees: ['UserGuides', 'AMDGPUUsage'], selecting: UserGuides <- AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack
  llvm/docs/AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst: document is referenced in multiple toctrees: ['UserGuides', 'AMDGPUUsage'], selecting: UserGuides <- AMDGPUDwarfExtensionsForHeterogeneousDebugging
  llvm/docs/CommandGuide/llvm-reduce.rst: document is referenced in multiple toctrees: ['CommandGuide/index', 'CommandGuide/index', 'Reference'], selecting: Reference <- CommandGuide/llvm-reduce
  llvm/docs/GitHub.rst: document is referenced in multiple toctrees: ['GettingInvolved', 'UserGuides'], selecting: UserGuides <- GitHub
  llvm/docs/GlobalISel/IRTranslator.rst: document is referenced in multiple toctrees: ['GlobalISel/index', 'GlobalISel/Pipeline'], selecting: GlobalISel/index <- GlobalISel/IRTranslator
  llvm/docs/GlobalISel/InstructionSelect.rst: document is referenced in multiple toctrees: ['GlobalISel/index', 'GlobalISel/Pipeline'], selecting: GlobalISel/index <- GlobalISel/InstructionSelect
  llvm/docs/GlobalISel/Legalizer.rst: document is referenced in multiple toctrees: ['GlobalISel/index', 'GlobalISel/Pipeline'], selecting: GlobalISel/index <- GlobalISel/Legalizer
  llvm/docs/GlobalISel/MIRPatterns.rst: document is referenced in multiple toctrees: ['GlobalISel/index', 'UserGuides'], selecting: UserGuides <- GlobalISel/MIRPatterns
  llvm/docs/GlobalISel/RegBankSelect.rst: document is referenced in multiple toctrees: ['GlobalISel/index', 'GlobalISel/Pipeline'], selecting: GlobalISel/index <- GlobalISel/RegBankSelect
  llvm/docs/TestSuiteGuide.md: document is referenced in multiple toctrees: ['Reference', 'TestingGuide'], selecting: TestingGuide <- TestSuiteGuide
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl01.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl01
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl02.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl02
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl03.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl03
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl04.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl04
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl05.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl05
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl06.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl06
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl07.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl07
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl08.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl08
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl09.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl09
  llvm/docs/tutorial/MyFirstLanguageFrontend/LangImpl10.rst: document is referenced in multiple toctrees: ['tutorial/index', 'tutorial/MyFirstLanguageFrontend/index'], selecting: tutorial/index <- tutorial/MyFirstLanguageFrontend/LangImpl10

I tried to preserve the documents as-is, by hiding `toctree`s and
instead using lists of `:doc:` forms where the `toctree` was visible
before.

The only visual change in the resulting HTML is that the link is now
underlined where it wasn't before.

I also nested the `Tutorials` section in GISel Porting document, and
didn't link to it directly as the title is a bit ambiguous without the
context of the document it appears in.

I also saw warnings about a jump in heading level in
llvm-debuginfo-analyzer/README.md and assumed it was just a mistake, so
I collapsed the level-3 headings down to level-2.

Change-Id: Icb11de69be1ea5489fba501aee4d767f5129e7e1



To unsubscribe from these emails, change your notification settings at https://github.com/llvm/llvm-project/settings/notifications