docs/reference: link module-related cmd/cue texts

This adds a programmatic "Related content" to module-related command help texts that mention other commands. The cross-linking is performed inside site.cue, but the data in commands.cue that drives the links has been extracted from the help texts manually. cue-lang/cue#3204 tracks the automation of help texts being included on the site, and might need to include the data included in this change after it's merged. Preview-Path: /docs/reference/command/cue-help-mod-get/ Preview-Path: /docs/reference/command/cue-help-mod-publish/ Preview-Path: /docs/reference/command/cue-help-mod-resolve/ Preview-Path: /docs/reference/command/cue-help-mod-tidy/ Preview-Path: /docs/reference/command/cue-help-modules/ Signed-off-by: Jonathan Matthews <[email protected]> Change-Id: I49736a213ada325f94054eb93b492b5a8249dbed Dispatch-Trailer: {"type":"trybot","CL":1200120,"patchset":6,"ref":"refs/changes/20/1200120/6","targetBranch":"master"}
cue-lang · Aug 29, 2024 · 6c76af6 · 6c76af6
1 parent b012aeb
commit 6c76af6
Show file tree

Hide file tree

Showing 14 changed files with 97 additions and 1 deletion.
diff --git a/content/docs/reference/command/commands.cue b/content/docs/reference/command/commands.cue
@@ -19,6 +19,7 @@ _cuePathBase: {
 	cuePath!: string
 	tagSet!: [string]: true // true is chosen over top purely to produce concrete data.
 	tagList!: [...]
+	relatedCommands!: [...string]
 
 	// oldDir is used to populate the page-level "aliases" front matter key,
 	// temporarily, until our logs show us that few enough inbound links reach
@@ -35,6 +36,7 @@ cue: [SubCommand=string]: #CueCommand & {
 	oldDir:     *"cue-\(_dirSuffix)" | _
 	tagSet: *{} | _
 	tagList: [for tag, _ in tagSet {tag}]
+	relatedCommands: *[] | _
 	cuePath: json.Marshal(_cuePathBase & {
 		_input: dir
 	})
@@ -75,6 +77,37 @@ tags: cue: {
 	]
 }
 
+// Related "docs/reference/command/" pages, manually extracted from help text
+// contents.
+cue: {
+	mod: relatedCommands: [
+		"cue help modules",
+		"cue help mod edit",
+		"cue help mod fix",
+		"cue help mod get",
+		"cue help mod init",
+		"cue help mod publish",
+		"cue help mod resolve",
+		"cue help mod tidy",
+	]
+	"mod get": relatedCommands: [
+		"cue help environment",
+	]
+	"mod publish": relatedCommands: [
+		"cue help environment",
+	]
+	"mod resolve": relatedCommands: [
+		"cue help registryconfig",
+	]
+	"mod tidy": relatedCommands: [
+		"cue help environment",
+	]
+	modules: relatedCommands: [
+		"cue help mod",
+		"cue help registryconfig",
+	]
+}
+
 // All commands
 cue: {
 	cue:            _

diff --git a/content/docs/reference/command/cue-help-mod-get/en.md b/content/docs/reference/command/cue-help-mod-get/en.md
@@ -11,3 +11,6 @@ tags:
 {{{with script "en" "cue cli help text"}}}
 cue help mod get
 {{{end}}}
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-environment" >}}
diff --git a/content/docs/reference/command/cue-help-mod-publish/en.md b/content/docs/reference/command/cue-help-mod-publish/en.md
@@ -11,3 +11,6 @@ tags:
 {{{with script "en" "cue cli help text"}}}
 cue help mod publish
 {{{end}}}
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-environment" >}}
diff --git a/content/docs/reference/command/cue-help-mod-resolve/en.md b/content/docs/reference/command/cue-help-mod-resolve/en.md
@@ -11,3 +11,6 @@ tags:
 {{{with script "en" "cue cli help text"}}}
 cue help mod resolve
 {{{end}}}
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-registryconfig" >}}
diff --git a/content/docs/reference/command/cue-help-mod-tidy/en.md b/content/docs/reference/command/cue-help-mod-tidy/en.md
@@ -11,3 +11,6 @@ tags:
 {{{with script "en" "cue cli help text"}}}
 cue help mod tidy
 {{{end}}}
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-environment" >}}
diff --git a/content/docs/reference/command/cue-help-mod/en.md b/content/docs/reference/command/cue-help-mod/en.md
@@ -11,3 +11,13 @@ tags:
 {{{with script "en" "cue cli help text"}}}
 cue help mod
 {{{end}}}
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-modules" >}}
+- {{< linkto/related/reference "command/cue-help-mod-edit" >}}
+- {{< linkto/related/reference "command/cue-help-mod-fix" >}}
+- {{< linkto/related/reference "command/cue-help-mod-get" >}}
+- {{< linkto/related/reference "command/cue-help-mod-init" >}}
+- {{< linkto/related/reference "command/cue-help-mod-publish" >}}
+- {{< linkto/related/reference "command/cue-help-mod-resolve" >}}
+- {{< linkto/related/reference "command/cue-help-mod-tidy" >}}
diff --git a/content/docs/reference/command/cue-help-modules/en.md b/content/docs/reference/command/cue-help-modules/en.md
@@ -11,3 +11,7 @@ tags:
 {{{with script "en" "cue cli help text"}}}
 cue help modules
 {{{end}}}
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-mod" >}}
+- {{< linkto/related/reference "command/cue-help-registryconfig" >}}
diff --git a/hugo/content/en/docs/reference/command/cue-help-mod-get/index.md b/hugo/content/en/docs/reference/command/cue-help-mod-get/index.md
@@ -45,3 +45,6 @@ Global Flags:
       --trace        trace computation
   -v, --verbose      print information about progress
 ```
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-environment" >}}
diff --git a/hugo/content/en/docs/reference/command/cue-help-mod-publish/index.md b/hugo/content/en/docs/reference/command/cue-help-mod-publish/index.md
@@ -42,3 +42,6 @@ Global Flags:
       --trace        trace computation
   -v, --verbose      print information about progress
 ```
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-environment" >}}
diff --git a/hugo/content/en/docs/reference/command/cue-help-mod-resolve/index.md b/hugo/content/en/docs/reference/command/cue-help-mod-resolve/index.md
@@ -39,3 +39,6 @@ Global Flags:
       --trace        trace computation
   -v, --verbose      print information about progress
 ```
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-registryconfig" >}}
diff --git a/hugo/content/en/docs/reference/command/cue-help-mod-tidy/index.md b/hugo/content/en/docs/reference/command/cue-help-mod-tidy/index.md
@@ -38,3 +38,6 @@ Global Flags:
       --trace        trace computation
   -v, --verbose      print information about progress
 ```
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-environment" >}}
diff --git a/hugo/content/en/docs/reference/command/cue-help-mod/index.md b/hugo/content/en/docs/reference/command/cue-help-mod/index.md
@@ -41,3 +41,13 @@ Global Flags:
 
 Use "cue mod [command] --help" for more information about a command.
 ```
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-modules" >}}
+- {{< linkto/related/reference "command/cue-help-mod-edit" >}}
+- {{< linkto/related/reference "command/cue-help-mod-fix" >}}
+- {{< linkto/related/reference "command/cue-help-mod-get" >}}
+- {{< linkto/related/reference "command/cue-help-mod-init" >}}
+- {{< linkto/related/reference "command/cue-help-mod-publish" >}}
+- {{< linkto/related/reference "command/cue-help-mod-resolve" >}}
+- {{< linkto/related/reference "command/cue-help-mod-tidy" >}}
diff --git a/hugo/content/en/docs/reference/command/cue-help-modules/index.md b/hugo/content/en/docs/reference/command/cue-help-modules/index.md
@@ -41,3 +41,7 @@ For information on how to specify the CUE registry:
 	cue help registryconfig
 
 ```
+## Related content
+
+- {{< linkto/related/reference "command/cue-help-mod" >}}
+- {{< linkto/related/reference "command/cue-help-registryconfig" >}}
diff --git a/site.cue b/site.cue
@@ -344,9 +344,20 @@ template: ci.#writefs & {
 					{{{with script "en" "cue cli help text"}}}
 					\#(cmd.execCmd)
 					{{{end}}}
-
+					\#( strings.Join([if len(cmd.relatedCommands) > 0 for e in [
+						"## Related content", "",
+						for c in cmd.relatedCommands
+						let path = strings.Replace(c, " ", "-", -1) {
+						#"- {{< linkto/related/reference "command/\#(path)" >}}"#
+					},
+				] {e},
+				], "\n"))
 					"""#
 			}
 		}
 	}
 }
+
+//		for _, related in cmd.relatedCommands {
+//			"- {{< linkto/related/reference \"command/\" >}}"
+//		}