Markdown generator failing due to library dependence

[rogercoll]

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/go-md2man@v1.0.10/md2man/md2man.go:11:16: undefined: blackfriday.EXTENSION_NO_INTRA_EMPHASIS ../../../go_projects/pkg/mod/github.com/cpuguy83/go-md2man@v1.0.10/md2man/md2man.go:12:16: undefined: blackfriday.EXTENSION_TABLES ../../../go_projects/pkg/mod/github.com/cpuguy83/go-md2man@v1.0.10/md2man/md2man.go:13:16: undefined: blackfriday.EXTENSION_FENCED_CODE ../../../go_projects/pkg/mod/github.com/cpuguy83/go-md2man@v1.0.10/md2man/md2man.go:14:16: undefined: blackfriday.EXTENSION_AUTOLINK ../../../go_projects/pkg/mod/github.com/cpuguy83/go-md2man@v1.0.10/md2man/md2man.go:15:16: undefined: blackfriday.EXTENSION_SPACE_HEADERS ../../../go_projects/pkg/mod/github.com/cpuguy83/go-md2man@v1.0.10/md2man/md2man.go:16:16: undefined: blackfriday.EXTENSION_FOOTNOTES ../../../go_projects/pkg/mod/github.com/cpuguy83/go-md2man@v1.0.10/md2man/md2man.go:17:16: undefined: blackfriday.EXTENSION_TITLEBLOCK ../../../go_projects/pkg/mod/github.com/cpuguy83/go-md2man@v1.0.10/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/go-md2man@v1.0.10/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/go-md2man@v1.0.10/md2man/roff.go:102:11: undefined: blackfriday.LIST_TYPE_ORDERED ../../../go_projects/pkg/mod/github.com/cpuguy83/go-md2man@v1.0.10/md2man/roff.go:102:11: too many errors

[umarcor]

Hi @rogercoll! Could you please provide the exact sequence of commands, so that we can reproduce the context?

[Pixcell]

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]

@rogercoll @umarcor ,

Looking at #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

[rogercoll]

@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

[umarcor]

@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?