github.com/linchen2chris/hugo@v0.0.0-20230307053224-cec209389705/commands/gendoc.go (about)

     1  // Copyright 2016 The Hugo Authors. All rights reserved.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  // http://www.apache.org/licenses/LICENSE-2.0
     7  //
     8  // Unless required by applicable law or agreed to in writing, software
     9  // distributed under the License is distributed on an "AS IS" BASIS,
    10  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    11  // See the License for the specific language governing permissions and
    12  // limitations under the License.
    13  
    14  package commands
    15  
    16  import (
    17  	"fmt"
    18  	"path"
    19  	"path/filepath"
    20  	"strings"
    21  
    22  	"github.com/gohugoio/hugo/helpers"
    23  	"github.com/gohugoio/hugo/hugofs"
    24  	"github.com/spf13/cobra"
    25  	"github.com/spf13/cobra/doc"
    26  	jww "github.com/spf13/jwalterweatherman"
    27  )
    28  
    29  var _ cmder = (*genDocCmd)(nil)
    30  
    31  type genDocCmd struct {
    32  	gendocdir string
    33  	*baseCmd
    34  }
    35  
    36  func newGenDocCmd() *genDocCmd {
    37  	const gendocFrontmatterTemplate = `---
    38  title: "%s"
    39  slug: %s
    40  url: %s
    41  ---
    42  `
    43  
    44  	cc := &genDocCmd{}
    45  
    46  	cc.baseCmd = newBaseCmd(&cobra.Command{
    47  		Use:   "doc",
    48  		Short: "Generate Markdown documentation for the Hugo CLI.",
    49  		Long: `Generate Markdown documentation for the Hugo CLI.
    50  
    51  This command is, mostly, used to create up-to-date documentation
    52  of Hugo's command-line interface for https://gohugo.io/.
    53  
    54  It creates one Markdown file per command with front matter suitable
    55  for rendering in Hugo.`,
    56  
    57  		RunE: func(cmd *cobra.Command, args []string) error {
    58  			cmd.VisitParents(func(c *cobra.Command) {
    59  				// Disable the "Auto generated by spf13/cobra on DATE"
    60  				// as it creates a lot of diffs.
    61  				c.DisableAutoGenTag = true
    62  			})
    63  
    64  			if !strings.HasSuffix(cc.gendocdir, helpers.FilePathSeparator) {
    65  				cc.gendocdir += helpers.FilePathSeparator
    66  			}
    67  			if found, _ := helpers.Exists(cc.gendocdir, hugofs.Os); !found {
    68  				jww.FEEDBACK.Println("Directory", cc.gendocdir, "does not exist, creating...")
    69  				if err := hugofs.Os.MkdirAll(cc.gendocdir, 0777); err != nil {
    70  					return err
    71  				}
    72  			}
    73  			prepender := func(filename string) string {
    74  				name := filepath.Base(filename)
    75  				base := strings.TrimSuffix(name, path.Ext(name))
    76  				url := "/commands/" + strings.ToLower(base) + "/"
    77  				return fmt.Sprintf(gendocFrontmatterTemplate, strings.Replace(base, "_", " ", -1), base, url)
    78  			}
    79  
    80  			linkHandler := func(name string) string {
    81  				base := strings.TrimSuffix(name, path.Ext(name))
    82  				return "/commands/" + strings.ToLower(base) + "/"
    83  			}
    84  			jww.FEEDBACK.Println("Generating Hugo command-line documentation in", cc.gendocdir, "...")
    85  			doc.GenMarkdownTreeCustom(cmd.Root(), cc.gendocdir, prepender, linkHandler)
    86  			jww.FEEDBACK.Println("Done.")
    87  
    88  			return nil
    89  		},
    90  	})
    91  
    92  	cc.cmd.PersistentFlags().StringVar(&cc.gendocdir, "dir", "/tmp/hugodoc/", "the directory to write the doc.")
    93  
    94  	// For bash-completion
    95  	cc.cmd.PersistentFlags().SetAnnotation("dir", cobra.BashCompSubdirsInDir, []string{})
    96  
    97  	return cc
    98  }