From b6e69606284b1102e67e1fd081670e617fa04743 Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Wed, 28 Aug 2024 11:53:50 +0100 Subject: [PATCH] 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 Change-Id: I49736a213ada325f94054eb93b492b5a8249dbed Dispatch-Trailer: {"type":"trybot","CL":1200120,"patchset":4,"ref":"refs/changes/20/1200120/4","targetBranch":"master"} --- content/docs/reference/command/commands.cue | 33 +++++++++++++++++++ .../reference/command/cue-help-mod-get/en.md | 3 ++ .../command/cue-help-mod-publish/en.md | 3 ++ .../command/cue-help-mod-resolve/en.md | 3 ++ .../reference/command/cue-help-mod-tidy/en.md | 3 ++ .../docs/reference/command/cue-help-mod/en.md | 10 ++++++ .../reference/command/cue-help-modules/en.md | 4 +++ .../command/cue-help-mod-get/index.md | 3 ++ .../command/cue-help-mod-publish/index.md | 3 ++ .../command/cue-help-mod-resolve/index.md | 3 ++ .../command/cue-help-mod-tidy/index.md | 3 ++ .../reference/command/cue-help-mod/index.md | 10 ++++++ .../command/cue-help-modules/index.md | 4 +++ site.cue | 13 +++++++- 14 files changed, 97 insertions(+), 1 deletion(-) diff --git a/content/docs/reference/command/commands.cue b/content/docs/reference/command/commands.cue index 0f58044f3..5768e4838 100644 --- 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 index 2021d0990..df24608e3 100644 --- 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" >}} \ No newline at end of file diff --git a/content/docs/reference/command/cue-help-mod-publish/en.md b/content/docs/reference/command/cue-help-mod-publish/en.md index 7ad47973f..133172b22 100644 --- 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" >}} \ No newline at end of file diff --git a/content/docs/reference/command/cue-help-mod-resolve/en.md b/content/docs/reference/command/cue-help-mod-resolve/en.md index 6f6280a4d..ffc678809 100644 --- 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" >}} \ No newline at end of file diff --git a/content/docs/reference/command/cue-help-mod-tidy/en.md b/content/docs/reference/command/cue-help-mod-tidy/en.md index eec480368..7d46e5931 100644 --- 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" >}} \ No newline at end of file diff --git a/content/docs/reference/command/cue-help-mod/en.md b/content/docs/reference/command/cue-help-mod/en.md index af2d3ce1d..55e45f24d 100644 --- 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" >}} \ No newline at end of file diff --git a/content/docs/reference/command/cue-help-modules/en.md b/content/docs/reference/command/cue-help-modules/en.md index bc454cea1..613c2bf56 100644 --- 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" >}} \ No newline at end of file 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 index d0e665d0e..07fdce554 100644 --- 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" >}} \ No newline at end of file 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 index 3eb83439b..6c13e0613 100644 --- 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" >}} \ No newline at end of file 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 index 8d5ca8c7b..847a93c1c 100644 --- 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" >}} \ No newline at end of file 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 index 93e759fa3..7f6370a29 100644 --- 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" >}} \ No newline at end of file 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 index 4ba384431..d00f6c1d0 100644 --- 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" >}} \ No newline at end of file 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 index a3ff0cc6a..2995aef93 100644 --- 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" >}} \ No newline at end of file diff --git a/site.cue b/site.cue index 4cfec59ef..1bfc917fc 100644 --- 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/\" >}}" +// }