From c0672207a327bf86b79c4f8f25f97558d41877ae Mon Sep 17 00:00:00 2001
From: Kian Parvin <kian.parvin@canonical.com>
Date: Tue, 3 Dec 2024 15:09:06 +0200
Subject: [PATCH 1/2] chore: fix subcommand URI fragments

Links to a different section of text in markdown should use - instead of _ for links with spaces.
Also adds a newline before the line break marker in the index.
---
 documentation.go | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation.go b/documentation.go
index ed18aa52..2e370f88 100644
--- a/documentation.go
+++ b/documentation.go
@@ -328,7 +328,7 @@ func (c *documentationCommand) writeIndex(w io.Writer) error {
 		}
 		// TODO: handle subcommands ??
 	}
-	_, err = fmt.Fprintf(w, "---\n\n")
+	_, err = fmt.Fprintf(w, "\n---\n\n")
 	return err
 }
 
@@ -380,7 +380,7 @@ func (c *documentationCommand) formatCommand(ref commandReference, title bool, c
 			return fmt.Sprintf("%s%s", prefix, target)
 		},
 		LinkForSubcommand: func(s string) string {
-			return c.linkForCommand(strings.Join(append(commandSeq[1:], s), "_"))
+			return c.linkForCommand(strings.Join(append(commandSeq[1:], s), "-"))
 		},
 	})
 	return buf.String()

From eb95f3f238d61d7ff749a06de655b485c6d7016d Mon Sep 17 00:00:00 2001
From: Kian Parvin <kian.parvin@canonical.com>
Date: Wed, 4 Dec 2024 14:24:41 +0200
Subject: [PATCH 2/2] fix: always print usage

The usage was only printed if the command has arguments, common for `list` style commands. But these commands should also have a usage section in the docs.
---
 markdown.go             | 16 ++++++------
 markdown_test.go        | 56 +++++++++++++++++++++++++++++++++++++++++
 testdata/list-clouds.md | 23 +++++++++++++++++
 3 files changed, 86 insertions(+), 9 deletions(-)
 create mode 100644 testdata/list-clouds.md

diff --git a/markdown.go b/markdown.go
index 8693e574..2a9784b8 100644
--- a/markdown.go
+++ b/markdown.go
@@ -73,15 +73,13 @@ func PrintMarkdown(w io.Writer, cmd InfoCommand, opts MarkdownOptions) error {
 	fmt.Fprintln(&doc)
 
 	// Usage
-	if strings.TrimSpace(info.Args) != "" {
-		fmt.Fprintln(&doc, "## Usage")
-		fmt.Fprintf(&doc, "```")
-		fmt.Fprint(&doc, opts.UsagePrefix)
-		fmt.Fprintf(&doc, "%s [%ss] %s", info.Name, getFlagsName(info.FlagKnownAs), info.Args)
-		fmt.Fprintf(&doc, "```")
-		fmt.Fprintln(&doc)
-		fmt.Fprintln(&doc)
-	}
+	fmt.Fprintln(&doc, "## Usage")
+	fmt.Fprintf(&doc, "```")
+	fmt.Fprint(&doc, opts.UsagePrefix)
+	fmt.Fprintf(&doc, "%s [%ss] %s", info.Name, getFlagsName(info.FlagKnownAs), info.Args)
+	fmt.Fprintf(&doc, "```")
+	fmt.Fprintln(&doc)
+	fmt.Fprintln(&doc)
 
 	// Options
 	printFlags(&doc, cmd)
diff --git a/markdown_test.go b/markdown_test.go
index 1b115f9c..20bda7a0 100644
--- a/markdown_test.go
+++ b/markdown_test.go
@@ -105,3 +105,59 @@ func (*markdownSuite) TestOutput(c *gc.C) {
 	c.Assert(err, jc.ErrorIsNil)
 	c.Check(buf.String(), gc.Equals, string(expected))
 }
+
+// TestOutputWithoutArgs tests that the output of the PrintMarkdown function is
+// correct when a command does not need arguments, e.g. list commands.
+func (*markdownSuite) TestOutputWithoutArgs(c *gc.C) {
+	seeAlso := []string{"add-cloud", "update-cloud", "remove-cloud", "update-credential"}
+	subcommands := map[string]string{
+		"foo": "foo the bar baz",
+		"bar": "bar the baz foo",
+		"baz": "baz the foo bar",
+	}
+
+	command := &docTestCommand{
+		info: &cmd.Info{
+			Name:        "clouds",
+			Args:        "", //Empty args should still result in a usage field.
+			Purpose:     "List clouds.",
+			Doc:         "details for clouds...",
+			Examples:    "examples for clouds...",
+			SeeAlso:     seeAlso,
+			Aliases:     []string{"list-clouds"},
+			Subcommands: subcommands,
+		},
+	}
+
+	// These functions verify the provided argument is in the expected set.
+	linkForCommand := func(s string) string {
+		for _, cmd := range seeAlso {
+			if cmd == s {
+				return "https://docs.com/" + cmd
+			}
+		}
+		c.Fatalf("linkForCommand called with unexpected command %q", s)
+		return ""
+	}
+
+	linkForSubcommand := func(s string) string {
+		_, ok := subcommands[s]
+		if !ok {
+			c.Fatalf("linkForSubcommand called with unexpected subcommand %q", s)
+		}
+		return "https://docs.com/clouds/" + s
+	}
+
+	expected, err := os.ReadFile("testdata/list-clouds.md")
+	c.Assert(err, jc.ErrorIsNil)
+
+	var buf bytes.Buffer
+	err = cmd.PrintMarkdown(&buf, command, cmd.MarkdownOptions{
+		Title:             `Command "juju clouds"`,
+		UsagePrefix:       "juju ",
+		LinkForCommand:    linkForCommand,
+		LinkForSubcommand: linkForSubcommand,
+	})
+	c.Assert(err, jc.ErrorIsNil)
+	c.Check(buf.String(), gc.Equals, string(expected))
+}
diff --git a/testdata/list-clouds.md b/testdata/list-clouds.md
new file mode 100644
index 00000000..16d58419
--- /dev/null
+++ b/testdata/list-clouds.md
@@ -0,0 +1,23 @@
+# Command "juju clouds"
+
+> See also: [add-cloud](https://docs.com/add-cloud), [update-cloud](https://docs.com/update-cloud), [remove-cloud](https://docs.com/remove-cloud), [update-credential](https://docs.com/update-credential)
+
+**Aliases:** list-clouds
+
+## Summary
+List clouds.
+
+## Usage
+```juju clouds [options] ```
+
+## Examples
+examples for clouds...
+
+## Details
+details for clouds...
+
+## Subcommands
+- [bar](https://docs.com/clouds/bar)
+- [baz](https://docs.com/clouds/baz)
+- [foo](https://docs.com/clouds/foo)
+