Man support

clidocstool.go

@@ -17,10 +17,13 @@ package clidocstool
 import (
 	"errors"
 	"io"
+	"log"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
 )
 
 // Options defines options for cli-docs-tool
@@ -29,6 +32,8 @@ type Options struct {
 	SourceDir string
 	TargetDir string
 	Plugin    bool
+
+	ManHeader *doc.GenManHeader
 }
 
 // Client represents an active cli-docs-tool object
@@ -37,6 +42,8 @@ type Client struct {
 	source string
 	target string
 	plugin bool
+
+	manHeader *doc.GenManHeader
 }
 
 // New initializes a new cli-docs-tool client
@@ -48,9 +55,10 @@ func New(opts Options) (*Client, error) {
 		return nil, errors.New("source dir required")
 	}
 	c := &Client{
-		root:   opts.Root,
-		source: opts.SourceDir,
-		plugin: opts.Plugin,
+		root:      opts.Root,
+		source:    opts.SourceDir,
+		plugin:    opts.Plugin,
+		manHeader: opts.ManHeader,
 	}
 	if len(opts.TargetDir) == 0 {
 		c.target = c.source
@@ -73,9 +81,69 @@ func (c *Client) GenAllTree() error {
 	if err = c.GenYamlTree(c.root); err != nil {
 		return err
 	}
+	if err = c.GenManTree(c.root); err != nil {
+		return err
+	}
 	return nil
 }
 
+// loadLongDescription gets long descriptions and examples from markdown.
+func (c *Client) loadLongDescription(parentCmd *cobra.Command, generator string) error {
+	for _, cmd := range parentCmd.Commands() {
+		if cmd.HasSubCommands() {
+			if err := c.loadLongDescription(cmd, generator); err != nil {
+				return err
+			}
+		}
+		name := cmd.CommandPath()
+		if i := strings.Index(name, " "); i >= 0 {
+			// remove root command / binary name
+			name = name[i+1:]
+		}
+		if name == "" {
+			continue
+		}
+		mdFile := strings.ReplaceAll(name, " ", "_") + ".md"
+		sourcePath := filepath.Join(c.source, mdFile)
+		content, err := os.ReadFile(sourcePath)
+		if os.IsNotExist(err) {
+			log.Printf("WARN: %s does not exist, skipping Markdown examples for %s docs\n", mdFile, generator)
+			continue
+		}
+		if err != nil {
+			return err
+		}
+		applyDescriptionAndExamples(cmd, string(content))
+	}
+	return nil
+}
+
+// applyDescriptionAndExamples fills in cmd.Long and cmd.Example with the
+// "Description" and "Examples" H2 sections in  mdString (if present).
+func applyDescriptionAndExamples(cmd *cobra.Command, mdString string) {
+	sections := getSections(mdString)
+	var (
+		anchors []string
+		md      string
+	)
+	if sections["description"] != "" {
+		md, anchors = cleanupMarkDown(sections["description"])
+		cmd.Long = md
+		anchors = append(anchors, md)
+	}
+	if sections["examples"] != "" {
+		md, anchors = cleanupMarkDown(sections["examples"])
+		cmd.Example = md
+		anchors = append(anchors, md)
+	}
+	if len(anchors) > 0 {
+		if cmd.Annotations == nil {
+			cmd.Annotations = make(map[string]string)
+		}
+		cmd.Annotations["anchors"] = strings.Join(anchors, ",")
+	}
+}
+
 func fileExists(f string) bool {
 	info, err := os.Stat(f)
 	if os.IsNotExist(err) {

clidocstool_man.go

@@ -0,0 +1,74 @@
+// Copyright 2016 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package clidocstool
+
+import (
+	"fmt"
+	"log"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+// 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 (c *Client) GenManTree(cmd *cobra.Command) error {
+	if err := c.loadLongDescription(cmd, "man"); err != nil {
+		return err
+	}
+
+	if epoch := os.Getenv("SOURCE_DATE_EPOCH"); c.manHeader != nil && epoch != "" {
+		unixEpoch, err := strconv.ParseInt(epoch, 10, 64)
+		if err != nil {
+			return fmt.Errorf("invalid SOURCE_DATE_EPOCH: %v", err)
+		}
+		now := time.Unix(unixEpoch, 0)
+		c.manHeader.Date = &now
+	}
+
+	return c.genManTreeCustom(cmd)
+}
+
+func (c *Client) genManTreeCustom(cmd *cobra.Command) error {
+	for _, sc := range cmd.Commands() {
+		if err := c.genManTreeCustom(sc); err != nil {
+			return err
+		}
+	}
+
+	// always disable the addition of [flags] to the usage
+	cmd.DisableFlagsInUseLine = true
+
+	// always disable "spf13/cobra" auto gen tag
+	cmd.DisableAutoGenTag = true
+
+	// Skip the root command altogether, to prevent generating a useless
+	// md file for plugins.
+	if c.plugin && !cmd.HasParent() {
+		return nil
+	}
+
+	log.Printf("INFO: Generating Man for %q", cmd.CommandPath())
+
+	return doc.GenManTreeFromOpts(cmd, doc.GenManTreeOptions{
+		Header:           c.manHeader,
+		Path:             c.target,
+		CommandSeparator: "-",
+	})
+}

clidocstool_man_test.go

@@ -0,0 +1,93 @@
+// Copyright 2024 cli-docs-tool authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package clidocstool
+
+import (
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"testing"
+	"time"
+
+	"github.com/spf13/cobra/doc"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+//nolint:errcheck
+func TestGenManTree(t *testing.T) {
+	setup()
+	tmpdir := t.TempDir()
+
+	epoch, err := time.Parse("2006-Jan-02", "2020-Jan-10")
+	require.NoError(t, err)
+	t.Setenv("SOURCE_DATE_EPOCH", strconv.FormatInt(epoch.Unix(), 10))
+
+	require.NoError(t, copyFile(path.Join("fixtures", "buildx_stop.pre.md"), path.Join(tmpdir, "buildx_stop.md")))
+
+	c, err := New(Options{
+		Root:      dockerCmd,
+		SourceDir: tmpdir,
+		Plugin:    true,
+		ManHeader: &doc.GenManHeader{
+			Title:   "DOCKER",
+			Section: "1",
+			Source:  "Docker Community",
+			Manual:  "Docker User Manuals",
+		},
+	})
+	require.NoError(t, err)
+	require.NoError(t, c.GenManTree(dockerCmd))
+
+	seen := make(map[string]struct{})
+	remanpage := regexp.MustCompile(`\.\d+$`)
+
+	filepath.Walk("fixtures", func(path string, info fs.FileInfo, err error) error {
+		fname := filepath.Base(path)
+		// ignore dirs and any file that is not a manpage
+		if info.IsDir() || !remanpage.MatchString(fname) {
+			return nil
+		}
+		t.Run(fname, func(t *testing.T) {
+			seen[fname] = struct{}{}
+			require.NoError(t, err)
+
+			bres, err := os.ReadFile(filepath.Join(tmpdir, fname))
+			require.NoError(t, err)
+
+			bexc, err := os.ReadFile(path)
+			require.NoError(t, err)
+			assert.Equal(t, string(bexc), string(bres))
+		})
+		return nil
+	})
+
+	filepath.Walk(tmpdir, func(path string, info fs.FileInfo, err error) error {
+		fname := filepath.Base(path)
+		// ignore dirs and any file that is not a manpage
+		if info.IsDir() || !remanpage.MatchString(fname) {
+			return nil
+		}
+		t.Run("seen_"+fname, func(t *testing.T) {
+			if _, ok := seen[fname]; !ok {
+				t.Errorf("file %s not found in fixtures", fname)
+			}
+		})
+		return nil
+	})
+}

clidocstool_md_test.go

@@ -27,17 +27,18 @@ import (
 
 //nolint:errcheck
 func TestGenMarkdownTree(t *testing.T) {
+	setup()
 	tmpdir := t.TempDir()
 
 	require.NoError(t, copyFile(path.Join("fixtures", "buildx_stop.pre.md"), path.Join(tmpdir, "buildx_stop.md")))
 
 	c, err := New(Options{
-		Root:      buildxCmd,
+		Root:      dockerCmd,
 		SourceDir: tmpdir,
 		Plugin:    true,
 	})
 	require.NoError(t, err)
-	require.NoError(t, c.GenMarkdownTree(buildxCmd))
+	require.NoError(t, c.GenMarkdownTree(dockerCmd))
 
 	seen := make(map[string]struct{})