feat: exported PrintMarkdown function

[barrettj12]

Motivation

The juju/cmd library already includes a way to format a given command as Markdown. However, currently this is buried deep inside the implementation details of the internal documentation command. As a result, given just a cmd.Command, it is not easy to print a Markdown document for it.

To get around this, we have had to use nasty hacks, such as for the hook tools, where we created a "fake"/artificial supercommand for the hook tools and ran the embedded documentation command to generate the docs. https://github.com/juju/juju/blob/0ae8f81a9e5ecc3a50c35ea059861a000f3c6657/scripts/md-gen/hook-tools/main.go#L43-L60

Changes

This PR refactors this code to expose a top-level PrintMarkdown function. This function takes three arguments:

• the cmd.Command to print the Markdown for;
• an io.Writer which all output is printed to;
• a MarkdownOptions struct whose values affect the outputted Markdown. The intent is that more fields can be added to this struct in response to future needs, while maintaining backward compability. Currently the options include:
  • whether or not to print a title
  • a prefix for the command usage (in our case this would be "juju ", as the supercommand name is not stored in the command)
  • functions to provide link targets for command names. These generally depend on the environment and context in which we are generating the documentation.

As we continue to move towards generated documentation, this new function should make the generation much easier. For example, there are other cmd.Command implementations in juju (such as the agent introspection tools) which we want to create docs for. The intention furthermore is that the existing documentation command will be refactored to use this function internally.

I'm not guaranteeing the output will be exactly the same as before, but it should have parity information-wise and at least not regress in any way in terms of formatting.

As this PR extends the public API of this package in a backwards-compatible way, it may necessitate a new minor release v3.1.0.

Example usage

An example usage of this function could be:

file, err := os.Create("mydoc.md")
cmd.PrintMarkdown(file, &myCommand, cmd.MarkdownOptions{})
file.Close()

Documentation changes

Minor changes to generated Markdown:

• All generated Markdown docs previously had a redundant horizontal line at the end. This has now been removed.
• Command aliases are printed.

QA

Pull the 3.5 branch of juju/juju. Build the client and generate the documentation.

make go-client-build
juju documentation --split --out=./docs

Commit the generated documentation so we can compare it with the new docs.

Pull this branch of juju/cmd. In the root directory of the juju/juju/3.5 branch, create a go.work file:

go work init .
go work edit -replace=github.com/juju/cmd/v3=[path/to/this/branch]

Rebuild the Juju client:

make go-client-build

Now delete the ./docs folder and regenerate the documentation to see the changes.

TODO

• [x] error handling
• [x] unit tests
• [x] QA with Juju, check diff with current documentation

Links

Jira card: JUJU-6627