[llvm-branch-commits] [llvm] [4/4]: [docs] Enforce unambiguous toctree in llvm/docs (PR #203967)

[Scott Linder via llvm-branch-commits]

slinder1 wrote:

<details>
<summary>🛠️ Changes since last push (click to expand):</summary>

```diff
diff --git b/llvm/docs/CommandGuide/index.md a/llvm/docs/CommandGuide/index.md
@@ -1,104 +1,149 @@
 # LLVM Command Guide
 
-The following documents are command descriptions for all of the LLVM tools.
-These pages describe how to use the LLVM commands and what their options are.
-Note that these pages do not describe all of the options available for all
-tools. To get a complete listing, pass the `--help` (general options) or
-`--help-hidden` (general and debugging options) arguments to the tool you are
-interested in.
-
-## Basic Commands
-
 ```{toctree}
-:maxdepth: 1
+:hidden:
 
+FileCheck
+clang-tblgen
 dsymutil
+lit
 llc
+lldb-tblgen
 lli
 llubi
+llvm-addr2line
+llvm-ar
 llvm-as
+llvm-bcanalyzer
 llvm-cgdata
 llvm-config
 llvm-cov
+llvm-cxxfilt
 llvm-cxxmap
 llvm-debuginfo-analyzer
 llvm-diff
 llvm-dis
 llvm-dwarfdump
 llvm-dwarfutil
+llvm-exegesis
+llvm-extract
 llvm-extract-bundle-entry
+llvm-ifs
+llvm-install-name-tool
 llvm-ir2vec
 llvm-lib
 llvm-libtool-darwin
 llvm-link
 llvm-lipo
+llvm-locstats
 llvm-mc
 llvm-mca
+llvm-nm
+llvm-objcopy
+llvm-objdump
+llvm-offload-binary
 llvm-opt-report
 llvm-otool
+llvm-pdbutil
 llvm-profdata
+llvm-profgen
+llvm-ranlib
+llvm-readelf
 llvm-readobj
 llvm-reduce
+llvm-remarkutil
+llvm-size
 llvm-stress
+llvm-strings
+llvm-strip
 llvm-symbolizer
+llvm-tblgen
+llvm-test-mustache-spec
+llvm-tli-checker
+mlir-tblgen
 opt
+tblgen
 ```
 
-## GNU binutils replacements
+The following documents are command descriptions for all of the LLVM tools.
+These pages describe how to use the LLVM commands and what their options are.
+Note that these pages do not describe all of the options available for all
+tools. To get a complete listing, pass the `--help` (general options) or
+`--help-hidden` (general and debugging options) arguments to the tool you are
+interested in.
 
-```{toctree}
-:maxdepth: 1
+## Basic Commands
 
-llvm-addr2line
-llvm-ar
-llvm-cxxfilt
-llvm-install-name-tool
-llvm-nm
-llvm-objcopy
-llvm-objdump
-llvm-ranlib
-llvm-readelf
-llvm-size
-llvm-strings
-llvm-strip
-```
+* {doc}`dsymutil`
+* {doc}`llc`
+* {doc}`lli`
+* {doc}`llubi`
+* {doc}`llvm-as`
+* {doc}`llvm-cgdata`
+* {doc}`llvm-config`
+* {doc}`llvm-cov`
+* {doc}`llvm-cxxmap`
+* {doc}`llvm-debuginfo-analyzer`
+* {doc}`llvm-diff`
+* {doc}`llvm-dis`
+* {doc}`llvm-dwarfdump`
+* {doc}`llvm-dwarfutil`
+* {doc}`llvm-extract-bundle-entry`
+* {doc}`llvm-ir2vec`
+* {doc}`llvm-lib`
+* {doc}`llvm-libtool-darwin`
+* {doc}`llvm-link`
+* {doc}`llvm-lipo`
+* {doc}`llvm-mc`
+* {doc}`llvm-mca`
+* {doc}`llvm-opt-report`
+* {doc}`llvm-otool`
+* {doc}`llvm-profdata`
+* {doc}`llvm-readobj`
+* {doc}`llvm-reduce`
+* {doc}`llvm-stress`
+* {doc}`llvm-symbolizer`
+* {doc}`opt`
 
-## Debugging Tools
+## GNU binutils replacements
 
-```{toctree}
-:maxdepth: 1
+* {doc}`llvm-addr2line`
+* {doc}`llvm-ar`
+* {doc}`llvm-cxxfilt`
+* {doc}`llvm-install-name-tool`
+* {doc}`llvm-nm`
+* {doc}`llvm-objcopy`
+* {doc}`llvm-objdump`
+* {doc}`llvm-ranlib`
+* {doc}`llvm-readelf`
+* {doc}`llvm-size`
+* {doc}`llvm-strings`
+* {doc}`llvm-strip`
 
-llvm-extract
-llvm-bcanalyzer
-llvm-reduce
-```
+## Debugging Tools
+
+* {doc}`llvm-extract`
+* {doc}`llvm-bcanalyzer`
+* {doc}`llvm-reduce`
 
 ## Developer Tools
 
-```{toctree}
-:maxdepth: 1
-
-FileCheck
-tblgen
-clang-tblgen
-lldb-tblgen
-llvm-tblgen
-mlir-tblgen
-lit
-llvm-exegesis
-llvm-ifs
-llvm-locstats
-llvm-test-mustache-spec
-llvm-pdbutil
-llvm-profgen
-llvm-tli-checker
-llvm-offload-binary
-```
+* {doc}`FileCheck`
+* {doc}`tblgen`
+* {doc}`clang-tblgen`
+* {doc}`lldb-tblgen`
+* {doc}`llvm-tblgen`
+* {doc}`mlir-tblgen`
+* {doc}`lit`
+* {doc}`llvm-exegesis`
+* {doc}`llvm-ifs`
+* {doc}`llvm-locstats`
+* {doc}`llvm-test-mustache-spec`
+* {doc}`llvm-pdbutil`
+* {doc}`llvm-profgen`
+* {doc}`llvm-tli-checker`
+* {doc}`llvm-offload-binary`
 
 ## Remarks Tools
 
-```{toctree}
-:maxdepth: 1
-
-llvm-remarkutil
-```
+* {doc}`llvm-remarkutil`
diff --git b/llvm/docs/CommandGuide/index.rst a/llvm/docs/CommandGuide/index.rst
diff --git b/llvm/docs/GettingInvolved.md a/llvm/docs/GettingInvolved.md
@@ -17,7 +17,6 @@ SphinxQuickstartTemplate
 HowToSubmitABug
 BugLifeCycle
 CodingStandards
-GitHub
 GitBisecting
 GitRepositoryPolicy
 ```
diff --git b/llvm/docs/GettingInvolved.rst a/llvm/docs/GettingInvolved.rst
diff --git b/llvm/docs/Reference.md a/llvm/docs/Reference.md
@@ -11,7 +11,6 @@ LLVM and API reference documentation.
 
 HowToUseAttributes
 CommandGuide/index
-CommandGuide/llvm-reduce
 OptBisect
 SymbolizerMarkupFormat
 PDB/index
@@ -27,7 +26,6 @@ MIRLangRef
 GlobalISel/index
 ConvergentOperations
 TestingGuide
-TestSuiteGuide
 GwpAsan
 XRay
 XRayExample
@@ -148,7 +146,6 @@ XRayFDRFormat
 {doc}`TestSuiteGuide`
 :   Describes how to compile and run the test-suite benchmarks.
 
-
 {doc}`GwpAsan`
 :   A sampled heap memory error detection toolkit designed for production use.
 
diff --git b/llvm/docs/Reference.rst a/llvm/docs/Reference.rst
diff --git b/llvm/docs/UserGuides.md a/llvm/docs/UserGuides.md
@@ -48,7 +48,6 @@ InstCombineContributorGuide
 WritingAnLLVMBackend
 CodeGenerator
 TableGen/index
-GlobalISel/MIRPatterns
 MCJITDesignAndImplementation
 ORCv2
 JITLink
@@ -64,8 +63,6 @@ CompileCudaWithLLVM
 NVPTXUsage
 AMDGPUUsage
 AMDGPUAsyncOperations
-AMDGPUDwarfExtensionsForHeterogeneousDebugging
-AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack/AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack
 AMDGPUExecutionSynchronization
 AMDGPUMemoryModel
 SPIRVUsage
diff --git b/llvm/docs/UserGuides.rst a/llvm/docs/UserGuides.rst

```
</details>

https://github.com/llvm/llvm-project/pull/203967