gendoc.go (2983B)
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 }