Cobra: Markdown generator failing due to library dependence
When trying to build the markdown documentation using: https://github.com/spf13/cobra/blob/master/doc/md_docs.md
The following library fails on build: github.com/cpuguy83/go-md2man/md2man
# github.com/cpuguy83/go-md2man/md2man
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:11:16: undefined: blackfriday.EXTENSION_NO_INTRA_EMPHASIS
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:12:16: undefined: blackfriday.EXTENSION_TABLES
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:13:16: undefined: blackfriday.EXTENSION_FENCED_CODE
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:14:16: undefined: blackfriday.EXTENSION_AUTOLINK
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:15:16: undefined: blackfriday.EXTENSION_SPACE_HEADERS
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:16:16: undefined: blackfriday.EXTENSION_FOOTNOTES
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/md2man.go:17:16: undefined: blackfriday.EXTENSION_TITLEBLOCK
../../../go_projects/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)
../../../go_projects/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)
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:102:11: undefined: blackfriday.LIST_TYPE_ORDERED
../../../go_projects/pkg/mod/github.com/cpuguy83/[email protected]/md2man/roff.go:102:11: too many errors
rogercoll
All 5 comments
Hi @rogercoll! Could you please provide the exact sequence of commands, so that we can reproduce the context?
umarcor
on 30 Jul 2019
Hi @umarcor,
I am having the same issue.
Please find the relevant code below:
/*
* *******************************************************************************
* * Copyright (c) 2019 Edgeworx, Inc.
* *
* * This program and the accompanying materials are made available under the
* * terms of the Eclipse Public License v. 2.0 which is available at
* * http://www.eclipse.org/legal/epl-2.0
* *
* * SPDX-License-Identifier: EPL-2.0
* *******************************************************************************
*
*/
package cmd
import (
"fmt"
"os"
"strings"
"github.com/eclipse-iofog/iofogctl/pkg/util"
homedir "github.com/mitchellh/go-homedir"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
)
func newGenerateDocumentationCommand(rootCmd *cobra.Command) *cobra.Command {
// Find home directory.
home, err := homedir.Dir()
util.Check(err)
docDir := home + "/.iofog/docs/"
os.MkdirAll(docDir, 0755)
cmd := &cobra.Command{
Use: "documentation TYPE",
Hidden: true,
Short: "Generate iofogctl documentation",
Long: "Generate iofogctl documentation as markdown or man page",
Example: `iofogctl documentation md
iofogctl documentation man`,
Args: cobra.ExactValidArgs(1),
Run: func(cmd *cobra.Command, args []string) {
switch t := strings.ToLower(args[0]); t {
case "md":
mdDir := docDir + "md/"
os.MkdirAll(mdDir, 0755)
err := doc.GenMarkdownTree(rootCmd, mdDir)
util.Check(err)
util.PrintSuccess(fmt.Sprintf("markdown documentation generated at %s", mdDir))
case "man":
manDir := docDir + "man/"
os.MkdirAll(manDir, 0755)
header := &doc.GenManHeader{
Title: "iofogctl",
Section: "1",
}
err := doc.GenManTree(rootCmd, header, manDir)
util.Check(err)
util.PrintSuccess(fmt.Sprintf("man documentation generated at %s", manDir))
default:
util.Check(util.NewNotFoundError(fmt.Sprintf("%s documentation format not supported for documentation generation\n Supported types are MAN and MD", t)))
}
},
}
return cmd
}
Root command
/*
* *******************************************************************************
* * Copyright (c) 2019 Edgeworx, Inc.
* *
* * This program and the accompanying materials are made available under the
* * terms of the Eclipse Public License v. 2.0 which is available at
* * http://www.eclipse.org/legal/epl-2.0
* *
* * SPDX-License-Identifier: EPL-2.0
* *******************************************************************************
*
*/
package cmd
import (
"github.com/eclipse-iofog/iofogctl/internal/config"
"github.com/eclipse-iofog/iofogctl/pkg/iofog/client"
"github.com/eclipse-iofog/iofogctl/pkg/util"
"github.com/spf13/cobra"
)
const TitleHeader = " _ ____ __ __ \n" +
" (_)___ / __/___ ____ _____/ /_/ / \n" +
" / / __ \\/ /_/ __ \\/ __ `/ ___/ __/ / \n" +
" / / /_/ / __/ /_/ / /_/ / /__/ /_/ / \n" +
" /_/\\____/_/ \\____/\\__, /\\___/\\__/_/ \n" +
" /____/ \n"
const TitleMessage = "Welcome to the cool new iofogctl Cli!\n" +
"\n" +
"Use `iofogctl version` to display the current version.\n\n"
func printHeader() {
util.PrintInfo(TitleHeader)
util.PrintInfo("\n")
util.PrintInfo(TitleMessage)
}
func NewRootCommand() *cobra.Command {
var cmd = &cobra.Command{
Use: "iofogctl",
//Short: "ioFog Unified Command Line Interface",
PreRun: func(cmd *cobra.Command, args []string) {
printHeader()
},
Run: func(cmd *cobra.Command, args []string) {
cmd.SetArgs([]string{"-h"})
err := cmd.Execute()
util.Check(err)
},
SilenceErrors: true,
SilenceUsage: true,
}
// Initialize config filename
cobra.OnInitialize(initConfig)
// Global flags
cmd.PersistentFlags().StringVar(&configFilename, "config", "", "CLI configuration file (default is "+config.DefaultConfigPath+")")
cmd.PersistentFlags().StringP("namespace", "n", "default", "Namespace to execute respective command within")
cmd.PersistentFlags().BoolVarP(&util.Quiet, "quiet", "q", false, "Toggle for displaying verbose output")
cmd.PersistentFlags().BoolVarP(&client.Verbose, "verbose", "v", false, "Toggle for displaying verbose output of API client")
// Register all commands
cmd.AddCommand(
newConnectCommand(),
newDisconnectCommand(),
newDeployCommand(),
newDeleteCommand(),
newCreateCommand(),
newGetCommand(),
newDescribeCommand(),
newLogsCommand(),
newLegacyCommand(),
newVersionCommand(),
newBashCompleteCommand(cmd),
newGenerateDocumentationCommand(cmd),
)
return cmd
}
// Config file set by --config persistent flag
var configFilename string
// Callback for cobra on initialization
func initConfig() {
config.Init(configFilename)
}
Dependencies are managed by go dep
I can send you the Gopkg.lock and Gopkg.toml if you want
Build output:
github.com/eclipse-iofog/iofogctl/vendor/github.com/cpuguy83/go-md2man/md2man
# github.com/eclipse-iofog/iofogctl/vendor/github.com/cpuguy83/go-md2man/md2man
vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go:11:16: undefined: blackfriday.EXTENSION_NO_INTRA_EMPHASIS
vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go:12:16: undefined: blackfriday.EXTENSION_TABLES
vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go:13:16: undefined: blackfriday.EXTENSION_FENCED_CODE
vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go:14:16: undefined: blackfriday.EXTENSION_AUTOLINK
vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go:15:16: undefined: blackfriday.EXTENSION_SPACE_HEADERS
vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go:16:16: undefined: blackfriday.EXTENSION_FOOTNOTES
vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go:17:16: undefined: blackfriday.EXTENSION_TITLEBLOCK
vendor/github.com/cpuguy83/go-md2man/md2man/md2man.go:19:29: too many arguments to conversion to blackfriday.Markdown: blackfriday.Markdown(doc, renderer, extensions)
vendor/github.com/cpuguy83/go-md2man/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)
vendor/github.com/cpuguy83/go-md2man/md2man/roff.go:102:11: undefined: blackfriday.LIST_TYPE_ORDERED
vendor/github.com/cpuguy83/go-md2man/md2man/roff.go:102:11: too many errors
make: *** [build] Error 2
make build:
go build -v $(GOARGS) $(PACKAGE_DIR)/main.go
Pixcell
on 6 Aug 2019
@rogercoll @umarcor ,
Looking at https://github.com/spf13/cobra/issues/805,
I found out that locking the version of blackfriday to 1.5.2, instead of 2.0 as automatically detected, did the trick.
Gopkg.toml
[[override]]
name = "github.com/russross/blackfriday"
version = "1.5.2"
This solved the problem for me
Pixcell
on 6 Aug 2019
@Pixcell thanks for this arrangement. There's a problem with russross/blackfriday library in 2.0 version. For now, downgrade manually to 1.5.2
rogercoll
on 7 Aug 2019
@Pixcell, thanks for reporting the solution! Since Gopkg.toml is specific to go dep, and go mod is used in this repo instead, I believe there is little we can do.
Nonetheless, it might be worth adding a note in the README explaining why blackfriday <=2 is required. @rogercoll, do you have any reference we can use to explain why blackfray 2 cannot be used?
umarcor
on 9 Aug 2019
Related issues
andygrunwald
路
6Comments
icholy
路
6Comments
anentropic
路
4Comments
groenborg
路
5Comments
galileo-pkm
路
6Comments
Most helpful comment
@rogercoll @umarcor ,
Looking at https://github.com/spf13/cobra/issues/805,
I found out that locking the version of blackfriday to 1.5.2, instead of 2.0 as automatically detected, did the trick.
Gopkg.toml
This solved the problem for me