Improvements for gendoc command #578

Merged
fyrchik merged 5 commits from fyrchik/frostfs-node:fix-gendoc into master 2023-08-10 11:10:14 +00:00
5 changed files with 51 additions and 14 deletions

View file

@ -45,7 +45,7 @@ func init() {
rootCmd.AddCommand(storagecfg.RootCmd)
rootCmd.AddCommand(autocomplete.Command("frostfs-adm"))
rootCmd.AddCommand(gendoc.Command(rootCmd))
rootCmd.AddCommand(gendoc.Command(rootCmd, gendoc.Options{}))
}
func Execute() error {

View file

@ -85,7 +85,7 @@ func init() {
rootCmd.AddCommand(objectCli.Cmd)
rootCmd.AddCommand(containerCli.Cmd)
rootCmd.AddCommand(tree.Cmd)
rootCmd.AddCommand(gendoc.Command(rootCmd))
rootCmd.AddCommand(gendoc.Command(rootCmd, gendoc.Options{}))
}
func entryPoint(cmd *cobra.Command, _ []string) {

View file

@ -38,7 +38,7 @@ func init() {
blobovnicza.Root,
meta.Root,
writecache.Root,
gendoc.Command(command),
gendoc.Command(command, gendoc.Options{}),
)
}

4
debian/rules vendored
View file

@ -12,8 +12,8 @@ override_dh_auto_install:
echo $(DEB_BUILD_OPTIONS)
dh_auto_install
bin/frostfs-adm gendoc -t man man/
bin/frostfs-cli gendoc -t man man/
bin/frostfs-adm gendoc --type man man/
bin/frostfs-cli gendoc --type man man/
bin/frostfs-adm completion bash > debian/frostfs-adm.bash-completion
bin/frostfs-cli completion bash > debian/frostfs-cli.bash-completion

View file

@ -7,6 +7,7 @@ import (
"path/filepath"
"strings"
"text/template"
"time"
"github.com/spf13/cobra"
"github.com/spf13/cobra/doc"
@ -23,8 +24,48 @@ const (
extensionFlag = "extension"
)
// Options for doc generation.
type Options struct {
// Parameters for man generation. By default use (1) section and `FrostFS` source.
ManHeader *doc.GenManHeader
// TypeFlag is the flag to use for type, without leading `--`.
// Do not use unless really necessary.
// Default: `type`.
TypeFlag string
// DepthFlag is the flag to use for depth, without leading `--`.
// Do not use unless really necessary.
// Default: `depth`.
DepthFlag string
// ExtensionFlag is the flag to use for extension, without leading `--`.
// Do not use unless really necessary.
// Default: `extension`.
ExtensionFlag string
}
func (o *Options) fillDefaults() {
if o.ManHeader == nil {
now := time.Now()
o.ManHeader = &doc.GenManHeader{
Section: "1",
Source: "FrostFS",
Date: &now,
}
}
if o.TypeFlag == "" {
o.TypeFlag = gendocTypeFlag
}
if o.DepthFlag == "" {
o.DepthFlag = depthFlag
}
if o.ExtensionFlag == "" {
o.ExtensionFlag = extensionFlag
}
}
// Command returns command which generates user documentation for the argument.
func Command(rootCmd *cobra.Command) *cobra.Command {
func Command(rootCmd *cobra.Command, opts Options) *cobra.Command {
opts.fillDefaults()
gendocCmd := &cobra.Command{
Use: "gendoc <dir>",
Short: "Generate documentation for this command",
@ -65,11 +106,7 @@ In this case there is a number of helper functions which can be used:
case gendocMarkdown:
return doc.GenMarkdownTree(rootCmd, args[0])
case gendocMan:
hdr := &doc.GenManHeader{
Section: "1",
Source: "NSPCC & Morphbits",
}
return doc.GenManTree(rootCmd, hdr, args[0])
return doc.GenManTree(rootCmd, opts.ManHeader, args[0])
default:
return errors.New("type must be 'md' or 'man'")
}
@ -77,9 +114,9 @@ In this case there is a number of helper functions which can be used:
}
ff := gendocCmd.Flags()
ff.StringP(gendocTypeFlag, "t", gendocMarkdown, "Type for the documentation ('md' or 'man')")
ff.Int(depthFlag, 1, "If template is specified, unify all commands starting from depth in a single file. Default: 1.")
ff.StringP(extensionFlag, "e", "", "If the template is specified, string to append to the output file names")
ff.String(opts.TypeFlag, gendocMarkdown, "Type for the documentation ('md' or 'man')")
ff.Int(opts.DepthFlag, 1, "If template is specified, unify all commands starting from depth in a single file. Default: 1.")
ff.String(opts.ExtensionFlag, "", "If the template is specified, string to append to the output file names")
return gendocCmd
}