Fix up gke-deploy docs. #519

joonlim · 2019-07-10T19:49:23Z

No description provided.

joonlim · 2019-07-10T19:49:57Z

@imjasonh Docs were messed up due to an auto-formatter.

imjasonh · 2019-07-10T19:51:22Z

Are these tables generated by cobra? If not, can they be? It'd be nice to have one canonical documentation in Go which gets generated into Markdown.

joonlim · 2019-07-11T13:31:48Z

Are these tables generated by cobra? If not, can they be? It'd be nice to have one canonical documentation in Go which gets generated into Markdown.

Is there a cobra command that generates tables?

imjasonh · 2019-07-11T14:00:31Z

Are these tables generated by cobra? If not, can they be? It'd be nice to have one canonical documentation in Go which gets generated into Markdown.

Is there a cobra command that generates tables?

Not tables, as far as I know, but it can generate Markdown files at least. See crane docs, generated from here. We ensure the generated docs are up-to-date in CI.

joonlim · 2019-07-11T14:40:09Z

Are these tables generated by cobra? If not, can they be? It'd be nice to have one canonical documentation in Go which gets generated into Markdown.

Is there a cobra command that generates tables?

Not tables, as far as I know, but it can generate Markdown files at least. See crane docs, generated from here. We ensure the generated docs are up-to-date in CI.

I copied the structure in the example you gave. For some reason, I can't use the github.com/spf13/cobra/doc library as long as the vendor dir exists.

^ This problem also prevents me from being able to docker build

joonlim · 2019-07-11T14:55:50Z

Step #0: ?   	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/cmd	[no test files]
Step #0: ?   	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/cmd/apply	[no test files]
Step #0: ok  	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/cmd/common	0.010s
Step #0: ?   	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/cmd/prepare	[no test files]
Step #0: ?   	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/cmd/run	[no test files]
Step #0: ok  	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/core/cluster	0.006s
Step #0: ok  	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/core/gcp	0.003s
Step #0: ok  	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/core/image	0.003s
Step #0: ok  	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/core/resource	0.061s
Step #0: ok  	github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/deployer	35.033s
Step #0: # github.com/cpuguy83/go-md2man/md2man
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:11:16: undefined: blackfriday.EXTENSION_NO_INTRA_EMPHASIS
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:12:16: undefined: blackfriday.EXTENSION_TABLES
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:13:16: undefined: blackfriday.EXTENSION_FENCED_CODE
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:14:16: undefined: blackfriday.EXTENSION_AUTOLINK
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:15:16: undefined: blackfriday.EXTENSION_SPACE_HEADERS
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:16:16: undefined: blackfriday.EXTENSION_FOOTNOTES
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:17:16: undefined: blackfriday.EXTENSION_TITLEBLOCK
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:19:29: too many arguments to conversion to blackfriday.Markdown: blackfriday.Markdown(doc, renderer, extensions)
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:19:9: cannot use &roffRenderer literal (type *roffRenderer) as type blackfriday.Renderer in return argument:
Step #0: 	*roffRenderer does not implement blackfriday.Renderer (missing RenderFooter method)
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:102:11: undefined: blackfriday.LIST_TYPE_ORDERED
Step #0: /go/pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:102:11: too many errors
Finished Step #0

joonlim · 2019-07-11T15:04:15Z

Here's the problem I'm facing:

If I add _ "github.com/spf13/cobra/doc" to any of my source files and run ./update-dep.sh, I see this:

➜  ./update-deps.sh  
go: finding github.com/BurntSushi/xgb latest
go: finding github.com/coreos/pkg latest
go: finding sigs.k8s.io/structured-merge-diff latest
go: finding github.com/google/go-containerregistry latest
go: finding github.com/elazarl/goproxy latest
go: finding google.golang.org/genproto latest
go: finding gopkg.in/tomb.v1 latest
go: finding github.com/armon/consul-api latest
go: finding github.com/PuerkitoBio/urlesc latest
go: finding golang.org/x/sync latest
go: finding golang.org/x/sys latest
go: finding github.com/xiang90/probing latest
go: finding golang.org/x/oauth2 latest
go: finding github.com/google/pprof latest
go: finding golang.org/x/time latest
go: finding golang.org/x/exp latest
go: finding golang.org/x/tools latest
go: finding github.com/docker/spdystream latest
go: finding github.com/mwitkow/go-conntrack latest
go: finding golang.org/x/net latest
go: finding golang.org/x/lint latest
go: finding gopkg.in/check.v1 latest
go: finding github.com/mailru/easyjson latest
go: finding github.com/tmc/grpc-websocket-proxy latest
go: finding golang.org/x/crypto latest
go: finding k8s.io/gengo latest
go: finding k8s.io/apimachinery latest
go: finding k8s.io/kube-openapi latest
go: finding github.com/coreos/go-systemd latest
go: finding github.com/mxk/go-flowrate latest
go: finding golang.org/x/mobile latest
go: finding github.com/golang/groupcache latest
go: finding github.com/munnerz/goautoneg latest
go: finding golang.org/x/image latest
go: finding github.com/nightlyone/lockfile latest
go: finding github.com/kr/logfmt latest
go: finding github.com/prometheus/client_model latest
go: finding github.com/dgryski/go-sip13 latest
go: finding github.com/modern-go/concurrent latest
go: finding github.com/jstemmer/go-junit-report latest
go: finding github.com/alecthomas/template latest
go: finding github.com/golang/glog latest
go: finding github.com/alecthomas/units latest
go: finding github.com/sdboyer/constext latest
# github.com/cpuguy83/go-md2man/md2man
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:11:16: undefined: blackfriday.EXTENSION_NO_INTRA_EMPHASIS
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:12:16: undefined: blackfriday.EXTENSION_TABLES
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:13:16: undefined: blackfriday.EXTENSION_FENCED_CODE
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:14:16: undefined: blackfriday.EXTENSION_AUTOLINK
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:15:16: undefined: blackfriday.EXTENSION_SPACE_HEADERS
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:16:16: undefined: blackfriday.EXTENSION_FOOTNOTES
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:17:16: undefined: blackfriday.EXTENSION_TITLEBLOCK
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:19:29: too many arguments to conversion to blackfriday.Markdown: blackfriday.Markdown(doc, renderer, extensions)
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:19:9: cannot use &roffRenderer literal (type *roffRenderer) as type blackfriday.Renderer in return argument:
	*roffRenderer does not implement blackfriday.Renderer (missing RenderFooter method)
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:102:11: undefined: blackfriday.LIST_TYPE_ORDERED
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:102:11: too many errors

joonlim · 2019-07-11T16:50:04Z

Found a mention of the problem here: spf13/cobra#805

I'm not sure yet how to fix this in the vendor

joonlim · 2019-07-11T17:45:23Z

Looks to me that github.com/spf13/cobra/doc is importing an older version of github.com/cpuguy83/go-md2man when run with go get/go vendor. Looking into this.

imjasonh · 2019-07-11T17:48:29Z

Thanks for looking into this. In the meantime if you just want to get this PR merged and work on generating docs in a future change that's fine too, just let me know.

joonlim · 2019-07-11T18:15:39Z

I believe this is the issue:

cobra/doc relies on https://github.com/cpuguy83/go-md2man/, which relies on https://github.com/russross/blackfriday/.

The latest release of https://github.com/cpuguy83/go-md2man/ is 1.0.10, which is broken because it calls some variables in blackfriday that do not exist in the version that go-md2man is relying on: v2.0.1. The undefined variables exist in go-md2man version v1.5.2

However, running without vendor works because https://github.com/cpuguy83/go-md2man's master branch doesn't use said missing variables.

joonlim · 2019-07-11T18:37:28Z

^ It seems that https://github.com/cpuguy83/go-md2man/ 1.0.10 is supposed to reference blackfriday 1.5.2. I'm looking into why it's not working for me.

joonlim · 2019-07-11T19:30:23Z

^ I think the problem may be in the gke-deploy source.

If I have this in a separate:

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/GoogleCloudPlatform/cloud-builders/gke-deploy/cmd"
	"github.com/spf13/cobra"
	"github.com/spf13/cobra/doc"
)

var dir string
var root = &cobra.Command{
	Use:   "gendoc",
	Short: "Generate gke-deploy's help docs",
	Args:  cobra.NoArgs,
	Run: func(*cobra.Command, []string) {
		if err := doc.GenMarkdownTree(cmd.NewCommand(), dir); err != nil {
			log.Fatalln(err)
		}
	},
}

func init() {
	root.Flags().StringVarP(&dir, "dir", "d", ".", "Path to directory in which to generate docs")
}

func main() {
	if err := root.Execute(); err != nil {
		fmt.Println(err)
		os.Exit(1)
	}
}

and run go get on the dir, it fails:

➜  go get -u
go: finding github.com/GoogleCloudPlatform/cloud-builders/gke-deploy latest
go: finding github.com/PuerkitoBio/urlesc latest
go: finding github.com/BurntSushi/xgb latest
^Cgo: finding github.com/armon/consul-api latest
go: finding github.com/mxk/go-flowrate latest
go: finding github.com/coreos/go-systemd latest
go: finding google.golang.org/genproto latest
go: finding golang.org/x/net latest
go: finding github.com/mwitkow/go-conntrack latest
go: finding golang.org/x/lint latest
go: finding k8s.io/kube-openapi latest
go: finding github.com/golang/glog latest
go: finding github.com/munnerz/goautoneg latest
go: finding golang.org/x/tools latest
go: finding github.com/xiang90/probing latest
go: finding github.com/modern-go/concurrent latest
go: finding github.com/mailru/easyjson latest
go: finding github.com/docker/spdystream latest
go: finding golang.org/x/crypto latest
go: finding golang.org/x/sys latest
go: finding gopkg.in/check.v1 latest
go: finding github.com/kr/logfmt latest
go: finding github.com/google/go-containerregistry latest
go: finding github.com/elazarl/goproxy latest
go: finding github.com/google/pprof latest
go: finding golang.org/x/sync latest
go: finding golang.org/x/oauth2 latest
go: finding golang.org/x/exp latest
go: finding github.com/tmc/grpc-websocket-proxy latest
go: finding golang.org/x/mobile latest
go: finding k8s.io/apimachinery latest
go: finding gopkg.in/tomb.v1 latest
go: finding sigs.k8s.io/structured-merge-diff latest
go: finding github.com/jstemmer/go-junit-report latest
go: finding github.com/coreos/pkg latest
go: finding github.com/prometheus/client_model latest
go: finding k8s.io/gengo latest
go: finding github.com/golang/groupcache latest
go: finding golang.org/x/time latest
cgo: finding golang.org/x/image latest
ago: finding github.com/alecthomas/units latest
tgo: finding github.com/alecthomas/template latest
 mgo: finding github.com/dgryski/go-sip13 latest
ai# github.com/cpuguy83/go-md2man/md2man
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:11:16: undefined: blackfriday.EXTENSION_NO_INTRA_EMPHASIS
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:12:16: undefined: blackfriday.EXTENSION_TABLES
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:13:16: undefined: blackfriday.EXTENSION_FENCED_CODE
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:14:16: undefined: blackfriday.EXTENSION_AUTOLINK
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:15:16: undefined: blackfriday.EXTENSION_SPACE_HEADERS
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:16:16: undefined: blackfriday.EXTENSION_FOOTNOTES
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:17:16: undefined: blackfriday.EXTENSION_TITLEBLOCK
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:19:29: too many arguments to conversion to blackfriday.Markdown: blackfriday.Markdown(doc, renderer, extensions)
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:19:9: cannot use &roffRenderer literal (type *roffRenderer) as type blackfriday.Renderer in return argument:
	*roffRenderer does not implement blackfriday.Renderer (missing RenderFooter method)
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:102:11: undefined: blackfriday.LIST_TYPE_ORDERED
../../../../../pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:102:11: too many errors

joonlim · 2019-07-12T14:37:43Z

After many attempts, I've still not been able to find the root of the solution. One clue is that the go.sum file contains both https://github.com/russross/blackfriday/ v1.5.2 and v2.0.1.

I've decided to punt adding the help tool for now.

I've added the generated docs to this PR.

I've also copied over the work from @dorbin's PR to preemptively deal with merge conflicts.

gke-deploy/VENDOR-LICENSE

gke-deploy/go.mod

* Fix tables in docs. * Add cobra-generated docs and update README.md. * Fix go.mod.

Fix tables in docs.

f47dfef

googlebot added the cla: yes CLA looks good label Jul 10, 2019

joonlim changed the title ~~Fix tables in docs.~~ Fix up gke-deploy docs. Jul 12, 2019

Add cobra-generated docs and update README.md.

bfccc3f

joonlim mentioned this pull request Jul 12, 2019

Update README.md #514

Closed

imjasonh suggested changes Jul 12, 2019

View reviewed changes

gke-deploy/VENDOR-LICENSE Outdated Show resolved Hide resolved

gke-deploy/go.mod Outdated Show resolved Hide resolved

Fix go.mod.

494f7cd

imjasonh approved these changes Jul 12, 2019

View reviewed changes

imjasonh merged commit 1a09661 into GoogleCloudPlatform:master Jul 12, 2019

jakebiesinger-onduo pushed a commit to jakebiesinger/cloud-builders that referenced this pull request Nov 3, 2019

Fix up gke-deploy docs. (GoogleCloudPlatform#519)

a0b685a

* Fix tables in docs. * Add cobra-generated docs and update README.md. * Fix go.mod.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix up gke-deploy docs. #519

Fix up gke-deploy docs. #519

joonlim commented Jul 10, 2019

joonlim commented Jul 10, 2019

imjasonh commented Jul 10, 2019

joonlim commented Jul 11, 2019

imjasonh commented Jul 11, 2019

joonlim commented Jul 11, 2019 •

edited

Loading

joonlim commented Jul 11, 2019

joonlim commented Jul 11, 2019

joonlim commented Jul 11, 2019

joonlim commented Jul 11, 2019 •

edited

Loading

imjasonh commented Jul 11, 2019

joonlim commented Jul 11, 2019 •

edited

Loading

joonlim commented Jul 11, 2019

joonlim commented Jul 11, 2019

joonlim commented Jul 12, 2019

Fix up gke-deploy docs. #519

Fix up gke-deploy docs. #519

Conversation

joonlim commented Jul 10, 2019

joonlim commented Jul 10, 2019

imjasonh commented Jul 10, 2019

joonlim commented Jul 11, 2019

imjasonh commented Jul 11, 2019

joonlim commented Jul 11, 2019 • edited Loading

joonlim commented Jul 11, 2019

joonlim commented Jul 11, 2019

joonlim commented Jul 11, 2019

joonlim commented Jul 11, 2019 • edited Loading

imjasonh commented Jul 11, 2019

joonlim commented Jul 11, 2019 • edited Loading

joonlim commented Jul 11, 2019

joonlim commented Jul 11, 2019

joonlim commented Jul 12, 2019

joonlim commented Jul 11, 2019 •

edited

Loading

joonlim commented Jul 11, 2019 •

edited

Loading

joonlim commented Jul 11, 2019 •

edited

Loading