Merge pull request #122 from kian99/minor-qol-tweaks-v3

#122

# Description

This PR recreates #120.

This PR makes some minor QoL improvements:
1. (First commit) Links to a different section of text in markdown should use - instead of _ for links with spaces. If a command has subcommands, the generated markdown currently resemble `#command_subcommand` and wouldn't properly navigate, instead `#command-subcommand` works.

2. (First commit) There is no line break between the end of the index file and the markdown separator `----` which causes issues when converting the markdown to other formats.

3. (Second commit) Always print command usage. The usage is only printed if a command has arguments, commonly empty for `list` style commands. But these commands should also have a usage section in the docs.

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()

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)

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))
+}

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)
+