clidocstool

README

About

This is a library containing utilities to generate (reference) documentation for the docker CLI on docs.docker.com.

Disclaimer

This library is intended for use by Docker's CLIs, and is not intended to be a general-purpose utility. Various bits are hard-coded or make assumptions that are very specific to our use-case. Contributions are welcome, but we will not accept contributions to make this a general-purpose module.

Usage

To generate the documentation it's recommended to do so using a Go submodule in your repository.

We will use the example of docker/buildx and create a Go submodule in a docs folder (recommended):

$ mkdir docs
$ cd ./docs
$ go mod init github.com/docker/buildx/docs
$ go get github.com/docker/cli-docs-tool

Your go.mod should look like this:

module github.com/docker/buildx/docs

go 1.16

require (
	github.com/docker/cli-docs-tool v0.0.0
)

Next, create a file named main.go inside that directory containing the following Go code from example/main.go.

Running this example should produce the following output:

$ go run main.go
INFO: Generating Markdown for "docker buildx bake"
INFO: Generating Markdown for "docker buildx build"
INFO: Generating Markdown for "docker buildx create"
INFO: Generating Markdown for "docker buildx du"
...
INFO: Generating YAML for "docker buildx uninstall"
INFO: Generating YAML for "docker buildx use"
INFO: Generating YAML for "docker buildx version"
INFO: Generating YAML for "docker buildx"

Generated docs will be available in the ./docs folder of the project.

Contributing

Want to contribute? Awesome! You can find information about contributing to this project in the CONTRIBUTING.md

Documentation

Overview

Package clidocstool provides tools for generating CLI documentation.

Index

• type Client
  • func New(opts Options) (*Client, error)
  • func (c *Client) GenAllTree() error
  • func (c *Client) GenManTree(cmd *cobra.Command) error
  • func (c *Client) GenMarkdownTree(cmd *cobra.Command) error
  • func (c *Client) GenYamlTree(cmd *cobra.Command) error
• type Options

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client represents an active cli-docs-tool object

func New

func New(opts Options) (*Client, error)

New initializes a new cli-docs-tool client

func (*Client) GenAllTree

func (c *Client) GenAllTree() error

GenAllTree creates all structured ref files for this command and all descendants in the directory given.

func (*Client) GenManTree

func (c *Client) GenManTree(cmd *cobra.Command) error

GenManTree generates a man page for the command and all descendants. If SOURCE_DATE_EPOCH is set, in order to allow reproducible package builds, we explicitly set the build time to SOURCE_DATE_EPOCH.

func (*Client) GenMarkdownTree

func (c *Client) GenMarkdownTree(cmd *cobra.Command) error

GenMarkdownTree will generate a markdown page for this command and all descendants in the directory given.

func (*Client) GenYamlTree

func (c *Client) GenYamlTree(cmd *cobra.Command) error

GenYamlTree creates yaml structured ref files for this command and all descendants in the directory given. This function may not work correctly if your command names have `-` in them. If you have `cmd` with two subcmds, `sub` and `sub-third`, and `sub` has a subcommand called `third` it is undefined which help output will be in the file `cmd-sub-third.1`.

type Options

type Options struct {
	Root      *cobra.Command
	SourceDir string
	TargetDir string
	Plugin    bool

	ManHeader *doc.GenManHeader
}

Options defines options for cli-docs-tool