Коммит
f6da7a61a0
108
README.md
108
README.md
|
@ -1,18 +1,116 @@
|
|||
[![PkgGoDev](https://img.shields.io/badge/go.dev-docs-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/docker/docgen)
|
||||
[![Test Status](https://img.shields.io/github/workflow/status/crazy-max/docgen/build?label=build&logo=github&style=flat-square)](https://github.com/docker/docgen/actions?query=workflow%3Atest)
|
||||
[![Test Status](https://img.shields.io/github/workflow/status/crazy-max/docgen/build?label=test&logo=github&style=flat-square)](https://github.com/docker/docgen/actions?query=workflow%3Atest)
|
||||
[![Go Report Card](https://goreportcard.com/badge/github.com/docker/docgen)](https://goreportcard.com/report/github.com/docker/docgen)
|
||||
|
||||
## About
|
||||
|
||||
Doc generator specially crafted for [Docker CLI](https://github.com/docker/cli) plugins.
|
||||
This is a library containing utilities to generate (reference) documentation
|
||||
for the [`docker` CLI](https://github.com/docker/cli) on [docs.docker.com](https://docs.docker.com/reference/).
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
go get github.com/docker/docgen
|
||||
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):
|
||||
|
||||
```console
|
||||
$ mkdir docs
|
||||
$ cd ./docs
|
||||
$ go mod init github.com/docker/buildx/docs
|
||||
$ go get github.com/docker/docgen
|
||||
```
|
||||
|
||||
Basic usage available in [example](example) folder.
|
||||
Your `go.mod` should look like this:
|
||||
|
||||
```text
|
||||
module github.com/docker/buildx/docs
|
||||
|
||||
go 1.16
|
||||
|
||||
require (
|
||||
github.com/docker/docgen v0.0.0
|
||||
)
|
||||
```
|
||||
|
||||
Next, create a file named `docgen.go` inside that directory containing the
|
||||
following Go code:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
"os"
|
||||
"path/filepath"
|
||||
|
||||
"github.com/docker/buildx/commands"
|
||||
"github.com/docker/cli/cli/command"
|
||||
"github.com/docker/docgen"
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
const sourcePath = "docs/"
|
||||
|
||||
func main() {
|
||||
log.SetFlags(0)
|
||||
|
||||
dockerCLI, err := command.NewDockerCli()
|
||||
if err != nil {
|
||||
log.Printf("ERROR: %+v", err)
|
||||
}
|
||||
|
||||
cmd := &cobra.Command{
|
||||
Use: "docker [OPTIONS] COMMAND [ARG...]",
|
||||
Short: "The base command for the Docker CLI.",
|
||||
DisableAutoGenTag: true,
|
||||
}
|
||||
|
||||
cmd.AddCommand(commands.NewRootCmd("buildx", true, dockerCLI))
|
||||
docgen.DisableFlagsInUseLine(cmd)
|
||||
|
||||
cwd, _ := os.Getwd()
|
||||
source := filepath.Join(cwd, sourcePath)
|
||||
|
||||
// Make sure "source" folder is created first
|
||||
if err = os.MkdirAll(source, 0755); err != nil {
|
||||
log.Printf("ERROR: %+v", err)
|
||||
}
|
||||
|
||||
// Generate Markdown and YAML documentation to "source" folder
|
||||
if err = docgen.GenTree(cmd, source); err != nil {
|
||||
log.Printf("ERROR: %+v", err)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Here we create a new instance of Docker CLI with `command.NewDockerCli` and a
|
||||
subcommand `commands.NewRootCmd` for `buildx`.
|
||||
|
||||
Finally, we generate Markdown and YAML documentation with `docgen.GenTree`.
|
||||
|
||||
```console
|
||||
$ 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
|
||||
|
||||
|
|
|
@ -41,7 +41,7 @@ func GenMarkdownTree(cmd *cobra.Command, dir string) error {
|
|||
return nil
|
||||
}
|
||||
|
||||
log.Printf("INFO: Generating Markdown docs for %s", cmd.CommandPath())
|
||||
log.Printf("INFO: Generating Markdown for %q", cmd.CommandPath())
|
||||
mdFile := mdFilename(cmd)
|
||||
fullPath := filepath.Join(dir, mdFile)
|
||||
|
||||
|
|
|
@ -112,7 +112,7 @@ func GenYamlTreeCustom(cmd *cobra.Command, dir string, filePrepender func(string
|
|||
if !cmd.HasParent() {
|
||||
return nil
|
||||
}
|
||||
|
||||
log.Printf("INFO: Generating YAML for %q", cmd.CommandPath())
|
||||
basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".yaml"
|
||||
filename := filepath.Join(dir, basename)
|
||||
f, err := os.Create(filename)
|
||||
|
@ -346,7 +346,6 @@ func loadLongDescription(parentCmd *cobra.Command, path string) error {
|
|||
}
|
||||
}
|
||||
name := cmd.CommandPath()
|
||||
log.Println("INFO: Generating YAML docs for", name)
|
||||
if i := strings.Index(name, " "); i >= 0 {
|
||||
// remove root command / binary name
|
||||
name = name[i+1:]
|
||||
|
@ -358,7 +357,7 @@ func loadLongDescription(parentCmd *cobra.Command, path string) error {
|
|||
fullPath := filepath.Join(path, mdFile)
|
||||
content, err := ioutil.ReadFile(fullPath)
|
||||
if os.IsNotExist(err) {
|
||||
log.Printf("WARN: %s does not exist, skipping\n", mdFile)
|
||||
log.Printf("WARN: %s does not exist, skipping Markdown examples for YAML doc\n", mdFile)
|
||||
continue
|
||||
}
|
||||
if err != nil {
|
||||
|
|
|
@ -1,6 +1,7 @@
|
|||
# Example
|
||||
|
||||
The following example will generate YAML and Markdown for [Docker buildx](https://github.com/docker/buildx) CLI plugin.
|
||||
The following example will generate YAML and Markdown docs for
|
||||
[Docker buildx](https://github.com/docker/buildx) CLI.
|
||||
|
||||
```console
|
||||
git clone https://github.com/docker/docgen
|
||||
|
|
|
@ -25,7 +25,7 @@ import (
|
|||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
const sourcePath = "docs/reference/"
|
||||
const sourcePath = "docs/"
|
||||
|
||||
func main() {
|
||||
log.SetFlags(0)
|
||||
|
|
Загрузка…
Ссылка в новой задаче