2020-08-08 17:14:55 +00:00
package main
import (
2020-10-26 12:55:03 +00:00
"bytes"
"fmt"
"io"
"os"
"path/filepath"
"strings"
2020-09-02 12:20:33 +00:00
2022-09-19 20:23:45 +00:00
"gitlab.com/gitlab-org/cli/pkg/iostreams"
2021-01-28 22:38:32 +00:00
2021-01-18 23:06:25 +00:00
"github.com/spf13/cobra/doc"
"github.com/spf13/pflag"
2020-10-26 12:55:03 +00:00
"github.com/spf13/cobra"
2022-09-19 20:23:45 +00:00
"gitlab.com/gitlab-org/cli/commands"
"gitlab.com/gitlab-org/cli/commands/cmdutils"
"gitlab.com/gitlab-org/cli/internal/config"
2020-08-08 17:14:55 +00:00
)
func main ( ) {
2021-01-18 23:06:25 +00:00
var flagErr pflag . ErrorHandling
docsCmd := pflag . NewFlagSet ( "" , flagErr )
manpage := docsCmd . BoolP ( "manpage" , "m" , false , "Generate manual pages instead of web docs" )
path := docsCmd . StringP ( "path" , "p" , "./docs/source/" , "Path where you want the generated docs saved" )
help := docsCmd . BoolP ( "help" , "h" , false , "Help about any command" )
if err := docsCmd . Parse ( os . Args ) ; err != nil {
fatal ( err )
}
if * help {
_ , err := fmt . Fprintf ( os . Stderr , "Usage of %s:\n\n%s" , os . Args [ 0 ] , docsCmd . FlagUsages ( ) )
if err != nil {
fatal ( err )
}
os . Exit ( 1 )
}
2022-11-17 18:36:09 +00:00
err := os . MkdirAll ( * path , 0 o755 )
2021-01-18 23:06:25 +00:00
if err != nil {
fatal ( err )
}
2020-10-26 12:55:03 +00:00
2021-01-28 23:07:05 +00:00
ioStream , _ , _ , _ := iostreams . Test ( )
2021-01-18 23:06:25 +00:00
glabCli := commands . NewCmdRoot ( & cmdutils . Factory { IO : ioStream } , "" , "" )
2020-10-26 12:55:03 +00:00
glabCli . DisableAutoGenTag = true
2021-01-18 23:06:25 +00:00
if * manpage {
if err := genManPage ( glabCli , * path ) ; err != nil {
fatal ( err )
}
} else {
if err := genWebDocs ( glabCli , * path ) ; err != nil {
fatal ( err )
}
}
}
func genManPage ( glabCli * cobra . Command , path string ) error {
header := & doc . GenManHeader {
Title : "glab" ,
Section : "1" ,
Source : "" ,
Manual : "" ,
}
err := doc . GenManTree ( glabCli , header , path )
if err != nil {
return err
}
return nil
}
func genWebDocs ( glabCli * cobra . Command , path string ) error {
2020-10-26 12:55:03 +00:00
cmds := glabCli . Commands ( )
for _ , cmd := range cmds {
fmt . Println ( "Generating docs for " + cmd . Name ( ) )
// create directories for parent commands
2022-11-17 18:36:09 +00:00
_ = os . MkdirAll ( path + cmd . Name ( ) , 0 o750 )
2020-10-26 12:55:03 +00:00
// Generate parent command
out := new ( bytes . Buffer )
2022-10-17 17:46:38 +00:00
err := GenMarkdownCustom ( cmd , out )
2020-10-26 12:55:03 +00:00
if err != nil {
2021-01-18 23:06:25 +00:00
return err
2020-10-26 12:55:03 +00:00
}
// Generate children commands
for _ , cmdC := range cmd . Commands ( ) {
2022-10-24 02:47:33 +00:00
if cmdC . HasAvailableSubCommands ( ) {
fmt . Println ( "Generating subcommand docs for " + cmdC . Name ( ) )
2022-11-17 18:36:09 +00:00
_ = os . MkdirAll ( path + cmd . Name ( ) + "/" + cmdC . Name ( ) , 0 o750 )
2022-10-24 02:47:33 +00:00
// Generate parent command
out := new ( bytes . Buffer )
err := GenMarkdownCustom ( cmdC , out )
if err != nil {
return err
}
2022-11-17 18:36:09 +00:00
err = config . WriteFile ( path + cmd . Name ( ) + "/" + cmdC . Name ( ) + "/index.md" , out . Bytes ( ) , 0 o755 )
2022-10-24 02:47:33 +00:00
if err != nil {
return err
}
for _ , cmdCC := range cmdC . Commands ( ) {
if cmdCC . Name ( ) != "help" {
err = GenMarkdownTreeCustom ( cmdCC , path + cmd . Name ( ) + "/" + cmdC . Name ( ) )
if err != nil {
return err
}
}
}
} else {
err = GenMarkdownTreeCustom ( cmdC , path + cmd . Name ( ) )
if err != nil {
return err
}
2020-10-26 12:55:03 +00:00
}
}
2022-11-17 18:36:09 +00:00
err = config . WriteFile ( path + cmd . Name ( ) + "/index.md" , out . Bytes ( ) , 0 o755 )
2020-10-26 12:55:03 +00:00
if err != nil {
2021-01-18 23:06:25 +00:00
return err
2020-10-26 12:55:03 +00:00
}
}
2021-01-18 23:06:25 +00:00
return nil
2020-10-26 12:55:03 +00:00
}
func printSubcommands ( cmd * cobra . Command , buf * bytes . Buffer ) {
if len ( cmd . Commands ( ) ) < 1 {
return
}
2022-10-17 17:46:38 +00:00
var subcommands string
2020-10-26 12:55:03 +00:00
// Generate children commands
for _ , cmdC := range cmd . Commands ( ) {
if cmdC . Name ( ) != "help" {
2022-10-24 02:47:33 +00:00
if cmdC . HasAvailableSubCommands ( ) {
subcommands += fmt . Sprintf ( "- [%s](%s/index.md)\n" , cmdC . Name ( ) , cmdC . Name ( ) )
} else {
subcommands += fmt . Sprintf ( "- [%s](%s.md)\n" , cmdC . Name ( ) , cmdC . Name ( ) )
}
2020-10-26 12:55:03 +00:00
}
}
if subcommands != "" {
2022-10-21 14:38:48 +00:00
buf . WriteString ( "\n## Subcommands\n\n" )
2020-10-26 12:55:03 +00:00
buf . WriteString ( subcommands )
}
}
func fatal ( err error ) {
fmt . Fprintln ( os . Stderr , err )
os . Exit ( 1 )
}
2022-10-17 17:46:38 +00:00
// adapted from : github.com/spf13/cobra/blob/main/doc/md_docs.go
// GenMarkdownTreeCustom is the the same as GenMarkdownTree, but
2020-10-26 12:55:03 +00:00
// with custom filePrepender and linkHandler.
2022-10-17 17:46:38 +00:00
func GenMarkdownTreeCustom ( cmd * cobra . Command , dir string ) error {
2020-10-26 12:55:03 +00:00
for _ , c := range cmd . Commands ( ) {
if ! c . IsAvailableCommand ( ) || c . IsAdditionalHelpTopicCommand ( ) {
continue
}
2022-10-17 17:46:38 +00:00
if err := GenMarkdownTreeCustom ( c , dir ) ; err != nil {
2020-10-26 12:55:03 +00:00
return err
}
}
2022-10-17 17:46:38 +00:00
basename := strings . ReplaceAll ( cmd . Name ( ) , " " , "_" ) + ".md"
2020-10-26 12:55:03 +00:00
filename := filepath . Join ( dir , basename )
f , err := os . Create ( filename )
2020-08-08 17:14:55 +00:00
if err != nil {
2020-10-26 12:55:03 +00:00
return err
}
defer f . Close ( )
2022-10-17 17:46:38 +00:00
if err := GenMarkdownCustom ( cmd , f ) ; err != nil {
2020-10-26 12:55:03 +00:00
return err
}
return nil
}
2022-10-17 17:46:38 +00:00
// GenMarkdownCustom creates custom Markdown output. github.com/spf13/cobra/blob/main/doc/md_docs.go
func GenMarkdownCustom ( cmd * cobra . Command , w io . Writer ) error {
2020-10-26 12:55:03 +00:00
cmd . InitDefaultHelpCmd ( )
cmd . InitDefaultHelpFlag ( )
buf := new ( bytes . Buffer )
name := cmd . CommandPath ( )
2022-11-17 18:36:09 +00:00
// GitLab Specific Docs Metadata
2022-10-17 17:46:38 +00:00
buf . WriteString ( "---" + "\n" )
buf . WriteString ( "stage: Create" + "\n" )
buf . WriteString ( "group: Code Review" + "\n" )
buf . WriteString ( "info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments" + "\n" )
buf . WriteString ( "---" + "\n\n" )
2020-10-26 12:55:03 +00:00
2022-11-17 18:36:09 +00:00
// Generated by a script
2022-10-19 14:32:40 +00:00
buf . WriteString ( "<!--" + "\n" )
2022-10-17 17:46:38 +00:00
buf . WriteString ( "This documentation is auto generated by a script." + "\n" )
buf . WriteString ( "Please do not edit this file directly, check cmd/gen-docs/docs.go." + "\n" )
2022-10-19 14:32:40 +00:00
buf . WriteString ( "-->" + "\n\n" )
2022-10-17 17:46:38 +00:00
2022-10-21 14:38:48 +00:00
buf . WriteString ( "# `" + name + "`\n\n" )
buf . WriteString ( cmd . Short + "\n" )
2022-10-17 17:46:38 +00:00
if len ( cmd . Long ) > 0 {
2022-10-21 14:38:48 +00:00
// Skipping `help` commands until Long description can be revised
if cmd . Name ( ) != "help" {
buf . WriteString ( "\n## Synopsis\n\n" )
buf . WriteString ( cmd . Long )
}
2022-10-17 17:46:38 +00:00
}
2020-10-26 12:55:03 +00:00
if cmd . Runnable ( ) {
2022-10-21 14:38:48 +00:00
buf . WriteString ( fmt . Sprintf ( "\n```plaintext\n%s\n```\n" , cmd . UseLine ( ) ) )
2020-10-26 12:55:03 +00:00
}
if len ( cmd . Example ) > 0 {
2022-10-21 14:38:48 +00:00
buf . WriteString ( "\n## Examples\n\n" )
buf . WriteString ( fmt . Sprintf ( "```plaintext\n%s\n```\n" , cmd . Example ) )
2020-10-26 12:55:03 +00:00
}
2022-10-17 17:46:38 +00:00
if err := printOptions ( buf , cmd , name ) ; err != nil {
2020-10-26 12:55:03 +00:00
return err
}
printSubcommands ( cmd , buf )
2022-10-18 01:16:30 +00:00
2020-10-26 12:55:03 +00:00
_ , err := buf . WriteTo ( w )
return err
}
2022-10-17 17:46:38 +00:00
// adapted from : github.com/spf13/cobra/blob/main/doc/md_docs.go
func printOptions ( buf * bytes . Buffer , cmd * cobra . Command , name string ) error {
2020-10-26 12:55:03 +00:00
flags := cmd . NonInheritedFlags ( )
flags . SetOutput ( buf )
if flags . HasAvailableFlags ( ) {
2022-10-21 14:38:48 +00:00
buf . WriteString ( "\n## Options\n\n```plaintext\n" )
2020-10-26 12:55:03 +00:00
flags . PrintDefaults ( )
2022-10-21 14:38:48 +00:00
buf . WriteString ( "```\n" )
2020-10-26 12:55:03 +00:00
}
parentFlags := cmd . InheritedFlags ( )
parentFlags . SetOutput ( buf )
if parentFlags . HasAvailableFlags ( ) {
2022-10-21 14:38:48 +00:00
buf . WriteString ( "\n## Options inherited from parent commands\n\n```plaintext\n" )
2020-10-26 12:55:03 +00:00
parentFlags . PrintDefaults ( )
2022-10-21 14:38:48 +00:00
buf . WriteString ( "```\n" )
2020-08-08 17:14:55 +00:00
}
2020-10-26 12:55:03 +00:00
return nil
2020-08-08 17:14:55 +00:00
}