Cli: Is it possible to generate static command documentation?

[bmatsuo]

I would like to have static documentation for my cli command. More specifically, I would like to have a link to HTML documentation for the command. But I think there are some problems to using godoc comments (and godoc.org) for this.

Does the cli package recommend some way other than godoc.org to achieve static docs?

These are the problems that I see with using godoc.org for command documentation:

• In the typical case, it will only document the latest (in-development) version of the application. People can avoid this by making sure their "master" branch is stable production code. But I don't think that is the norm.
• For cli commands, go doc comments are often either vague or redundant. The command help text and flags already document the command. And manually duplicating that information into the godoc comments is a pain -- which leads to out-of-sync comments.

The first problem is solved by generating static documentation -- command documentation can be embedded in the release archive (tarball), or hosted using something like github.io. The second problem could potentially be solved by having a "godoc" output option for the doc generator that spits out a doc.go file with command documentation.

(edit: I'm willing to help implement such a solution. But it sounds like a fairly impressive undertaking so I wanted to run it by the maintainers first)

[jszwedko]

I think this could also be addressed by adding the ability to generate man page documentation -- would that fit with what you are thinking?

[bmatsuo]

@jszwedko generating man pages would certainly be a start if that is possible. But I think what I am looking for ideally would be a more extensible solution. IMO man is a little archaic. And I don't know that it would be ideal on Windows (though I'm sure it probably does/can work).

I imagine that a set of man pages can be transformed into HTML using some existing tools. But I doubt the results look spectacular. And I am looking for something that produces reasonably modern looking HTML. Please point out anything you are aware of to do that @jszwedko :smile:

I imagine that the primary documentation reference for my project will be online. I intend on hosting versioned copies of generated documentation (so v1 docs at github.io/bmatsuo/foo/v1, v2 docs at github.io/bmatuso/foo/v2, etc). And I would like to style these docs to integrate with the project website as a whole.

I think something like sphynx doc generation may be more what I'm looking for. But from what I know I don't really like the look of sphynx generated sites.

I was thinking something along the lines of a Go interface that could could be implemented to generate man page documents, sphynx style docs, markdown, or raw HTML.

[yepher]

I could see a MarkDown output that then could be fed into any number of tools to generate PDF, DOC or any number of other outputs.

[jszwedko]

@bmatsuo gotcha, I see your use case now.

I think I agree with @yepher in that generating markdown is probably the most flexible since it can easily be transformed into other formats (via pandoc or others).

[jszwedko]

That being said, I think this would be great and would love to review a PR adding the functionality! Let me know what you think about the markdown approach.

[hasit]

@bmatsuo I think starting off with generating man pages is a good idea. I know for a fact that fish shell has a command to generate autocompletion/autosuggestion scripts from man pages. I am sure there are similar tools in other shells. So this feature would help out with completion scripts as well.

[bmatsuo]

That's a good point about Fish shell, @hasit. I don't use fish but I understand it is popular.

I haven't started working on any implementation myself either. I have been focused on a few other projects more recently, though I still care about this.

I think that extensibility should be part of the solution though, whatever that is. So, having the ability to generate man pages sounds fine. But I would really like the API to expose a way for applications to use custom text/template or html/template strings to format the documentation. This might be easiest through a function that generates a template 'context' (i.e. the data argument to the template Execute method).

Does that sound reasonable?

[yepher]

I was talking about the documentation feature to a Co-Worker and they showed me this library which seems to support Man Pages. See here

[Southclaws]

I might start hacking around with a Markdown generator tomorrow, I have a basic project with some subcommands, flags and args to use as a test bed and I want to generate some docs for it pretty soon anyway so I'll submit a PR if I make decent progress and see what everyone thinks about the implementation 👍

[Southclaws]

Made a pretty simple function to generate docs for commands and flags, my CLI app is pretty simple so I've probably missed out a bunch of features that I don't make use of:

// GenerateDocs generates markdown documentation for the commands in app
func GenerateDocs(app *cli.App) (result string) {
    buffer := bytes.Buffer{}

    buffer.WriteString(fmt.Sprintf("# `%s`\n%s - %s <%s>\n\n", app.Name, app.Version, app.Author, app.Email))

    if app.Description != "" {
        buffer.WriteString(app.Description)
        buffer.WriteString("\n\n")
    }

    buffer.WriteString("## Subcommands\n\n")

    for _, command := range app.Commands {
        buffer.WriteString(fmt.Sprintf("### `%s`\n\n", command.Name))
        if command.Usage != "" {
            buffer.WriteString(command.Usage)
            buffer.WriteString("\n\n")
        }
        if command.Description != "" {
            buffer.WriteString(command.Description)
            buffer.WriteString("\n\n")
        }
        if len(command.Flags) > 0 {
            buffer.WriteString("#### Flags\n\n")
            for _, flag := range command.Flags {
                buffer.WriteString(fmt.Sprintf("- `--%s`\n", flag.GetName()))
            }
            buffer.WriteString("\n\n")
        }
    }

    if len(app.Flags) > 0 {
        buffer.WriteString("## Global Flags\n\n")
        for _, flag := range app.Flags {
            buffer.WriteString(fmt.Sprintf("- `--%s`\n", flag.GetName()))
        }
        buffer.WriteString("\n\n")
    }
    return buffer.String()
}

Which turns this app declaration into the following document:

---

sampctl

1.2.6-R2 - Southclaws [e-mail]

A small utility for starting and managing SA:MP servers with better settings handling and crash resiliency.

Subcommands

init

initialise a sa-mp server folder with a few questions, uses the cwd if --dir is not set

Flags

• --version
• --dir
• --endpoint

run

run a sa-mp server, uses the cwd if --dir is not set

Flags

• --version
• --dir
• --endpoint
• --container

download

download a version of the server, uses latest if --version is not specified

Flags

• --version
• --dir
• --endpoint

exec

execute an amx file as a SA:MP gamemode for quick testing in a temporary server installation

Flags

• --version
• --dir
• --endpoint
• --container

docgen

generate documentation - mainly just for CI usage, the readme file will always be up to date.

help

Shows a list of commands or help for one command

Global Flags

• --help, h
• --app-version, V

[jribe]

@jszwedko I'm considering picking this work up, but writing the templates for markdown pages looks like a PITA in go source since markdown uses backticks and there's no way to escape backticks in a raw string. Would you be open to a PR that has templates in files that are loaded into source via vfsgen go:generate directives?

[jszwedko]

@jribe 👍 You could also consider template.ParseFiles from text/template.

[jribe]

I drew up an example of what a markdown doc page might look like over here: https://github.com/jribe/cli/wiki/Markdown-doc-example

Any thoughts on the format?

[lynncyrin]

Hey everyone! I'm just getting ramped up in this repo, but wanted to mention that this issue is definitely still available for someone to work up 🙏 You can tag me for PR reviews 👍

[saschagrunert]

I created a first stand alone docs generator here: https://github.com/saschagrunert/go-docgen

[lynncyrin]

@saschagrunert that looks great! Is there any way I could convince you to merge the docs generator functionality into this package?

I think users would love a CLI that includes that feature! And given that it would be a significant contribution, we almost certainly want you to be a collaborator on this project.

I also want to acknowledge that this repo was inactive until last week, so it makes sense that people would prefer to make standalone things! I'm just hoping to build a more collaborative future 🙏

[saschagrunert]

@saschagrunert that looks great! Is there any way I could convince you to merge the docs generator functionality into this package?

Yes sure why not. :) I will see how we can implement this and spin up a first PR for discussion.