From 9326690338c4f80e1d763963889857e08bfc0645 Mon Sep 17 00:00:00 2001 From: Keepers Date: Thu, 4 Aug 2022 16:46:14 -0600 Subject: [PATCH] autopopulate cli markdown on ci build (#453) --- .github/workflows/ci.yml | 6 +- .github/workflows/docgen.yml | 66 +++++++++++++++ .github/workflows/lint.yml | 8 +- docs/docs/cli/corso.md | 28 +++++++ docs/docs/cli/corso_backup.md | 33 ++++++++ docs/docs/cli/corso_backup_create.md | 27 +++++++ docs/docs/cli/corso_backup_create_exchange.md | 29 +++++++ docs/docs/cli/corso_backup_details.md | 27 +++++++ .../docs/cli/corso_backup_details_exchange.md | 34 ++++++++ docs/docs/cli/corso_backup_list.md | 27 +++++++ docs/docs/cli/corso_backup_list_exchange.md | 26 ++++++ docs/docs/cli/corso_repo.md | 32 ++++++++ docs/docs/cli/corso_repo_connect.md | 31 +++++++ docs/docs/cli/corso_repo_connect_s3.md | 34 ++++++++ docs/docs/cli/corso_repo_init.md | 31 +++++++ docs/docs/cli/corso_repo_init_s3.md | 34 ++++++++ docs/docs/cli/corso_restore.md | 31 +++++++ docs/docs/cli/corso_restore_exchange.md | 34 ++++++++ src/cli/cli.go | 41 +++++++--- src/cli/cli_test.go | 8 +- src/cli/repo/s3_integration_test.go | 14 +--- src/cmd/mdgen/mdgen.go | 80 +++++++++++++++++++ src/go.mod | 2 + src/go.sum | 2 + 24 files changed, 654 insertions(+), 31 deletions(-) create mode 100644 .github/workflows/docgen.yml create mode 100644 docs/docs/cli/corso.md create mode 100644 docs/docs/cli/corso_backup.md create mode 100644 docs/docs/cli/corso_backup_create.md create mode 100644 docs/docs/cli/corso_backup_create_exchange.md create mode 100644 docs/docs/cli/corso_backup_details.md create mode 100644 docs/docs/cli/corso_backup_details_exchange.md create mode 100644 docs/docs/cli/corso_backup_list.md create mode 100644 docs/docs/cli/corso_backup_list_exchange.md create mode 100644 docs/docs/cli/corso_repo.md create mode 100644 docs/docs/cli/corso_repo_connect.md create mode 100644 docs/docs/cli/corso_repo_connect_s3.md create mode 100644 docs/docs/cli/corso_repo_init.md create mode 100644 docs/docs/cli/corso_repo_init_s3.md create mode 100644 docs/docs/cli/corso_restore.md create mode 100644 docs/docs/cli/corso_restore_exchange.md create mode 100644 src/cmd/mdgen/mdgen.go diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d680fad7a..c9fb8f111 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,4 @@ -name: CI +name: CI Tests on: push: branches: [main] @@ -28,7 +28,6 @@ jobs: echo "::set-output name=go-build::$(go env GOCACHE)" echo "::set-output name=go-mod::$(go env GOMODCACHE)" - - name: Golang Setup uses: actions/setup-go@v3 with: @@ -60,7 +59,7 @@ jobs: if: steps.mybuild.outputs.cache-hit != 'true' run: go build -v ./... - # Alternatively, install using go install + # Install gotestfmt - name: Set up gotestfmt run: go install github.com/haveyoudebuggedit/gotestfmt/v2/cmd/gotestfmt@latest @@ -81,6 +80,7 @@ jobs: CLIENT_ID: ${{ secrets.CLIENT_ID }} CLIENT_SECRET: ${{ secrets.CLIENT_SECRET }} TENANT_ID: ${{ secrets.TENANT_ID }} + CORSO_M356_TEST_USER_ID: ${{ secrets.CORSO_M356_TEST_USER_ID }} run: | set -euo pipefail go test -json -v ./... 2>&1 | tee /tmp/gotest.log | gotestfmt -hide successful-tests diff --git a/.github/workflows/docgen.yml b/.github/workflows/docgen.yml new file mode 100644 index 000000000..fea56188b --- /dev/null +++ b/.github/workflows/docgen.yml @@ -0,0 +1,66 @@ +name: Document Generation +on: + pull_request: + branches: [main] + +jobs: + Run-All: + environment: Testing + runs-on: ubuntu-latest + steps: + + # check out the repo + - name: Repo Code Checkout + uses: actions/checkout@v3 + with: + ref: ${{ github.head_ref }} + + # Get values for cache paths to be used in later steps + - id: go-cache-paths + working-directory: ./src + run: | + echo "::set-output name=go-build::$(go env GOCACHE)" + echo "::set-output name=go-mod::$(go env GOMODCACHE)" + + - name: Golang Setup + uses: actions/setup-go@v3 + with: + go-version: 1.18 + cache: true + cache-dependency-path: src/go.sum + + # download packages + - name: Cache Go Mod + uses: actions/cache@v3 + id: cache + with: + path: ${{ steps.go-cache-paths.outputs.go-mod }} + key: ${{ runner.os }}-go-mod-${{ hashFiles('**/go.sum') }} + + - name: Run go mod download + if: steps.cache.outputs.cache-hit != 'true' + working-directory: ./src + run: go mod download + + # run the markdown generator + - name: Generate Markdown + working-directory: ./src + run: | + go run ./cmd/mdgen/mdgen.go generate + + # migrate generated md files into /docs/docs/cli + - name: Move CLI .md to Docs + run: | + mkdir -p ./docs/docs/cli + mv ./src/cmd/mdgen/cli_markdown/* ./docs/docs/cli/ + rm -R ./src/cmd/mdgen/cli_markdown/ + + # make a commit for any file changes + - name: Commit the Auto-Generated Files + uses: stefanzweifel/git-auto-commit-action@v4 + with: + commit_message: Documentation Auto-generation + commit_user_name: github-actions[bot] + commit_user_email: 41898282+github-actions[bot]@users.noreply.github.com + commit_author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com> + diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index a616aacc6..2eb592607 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -1,4 +1,4 @@ -name: Linting of Source Code +name: Lint on: push: branches: [main] @@ -16,6 +16,12 @@ jobs: - name: Checkout src code uses: actions/checkout@v3 + # Get values for cache paths to be used in later steps + - id: go-cache-paths + run: | + echo "::set-output name=go-build::$(go env GOCACHE)" + echo "::set-output name=go-mod::$(go env GOMODCACHE)" + - name: Golang Setup uses: actions/setup-go@v3 with: diff --git a/docs/docs/cli/corso.md b/docs/docs/cli/corso.md new file mode 100644 index 000000000..5c09e683e --- /dev/null +++ b/docs/docs/cli/corso.md @@ -0,0 +1,28 @@ +## corso + +Protect your Microsoft 365 data. + +### Synopsis + +Reliable, secure, and efficient data protection for Microsoft 365. + +``` +corso [flags] +``` + +### Options + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + -h, --help help for corso + --json output data in JSON format + -v, --version current version info +``` + +### SEE ALSO + +* [corso backup](corso_backup.md) - Backup your service data +* [corso repo](corso_repo.md) - Manage your repositories +* [corso restore](corso_restore.md) - Restore your service data + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_backup.md b/docs/docs/cli/corso_backup.md new file mode 100644 index 000000000..0a40be963 --- /dev/null +++ b/docs/docs/cli/corso_backup.md @@ -0,0 +1,33 @@ +## corso backup + +Backup your service data + +### Synopsis + +Backup the data stored in one of your M365 services. + +``` +corso backup [flags] +``` + +### Options + +``` + -h, --help help for backup +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso](corso.md) - Protect your Microsoft 365 data. +* [corso backup create](corso_backup_create.md) - Backup an M365 Service +* [corso backup details](corso_backup_details.md) - Shows the details of a backup for a service +* [corso backup list](corso_backup_list.md) - List the history of backups for a service + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_backup_create.md b/docs/docs/cli/corso_backup_create.md new file mode 100644 index 000000000..dd7dd1d5e --- /dev/null +++ b/docs/docs/cli/corso_backup_create.md @@ -0,0 +1,27 @@ +## corso backup create + +Backup an M365 Service + +``` +corso backup create [flags] +``` + +### Options + +``` + -h, --help help for create +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso backup](corso_backup.md) - Backup your service data +* [corso backup create exchange](corso_backup_create_exchange.md) - Backup M365 Exchange service data + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_backup_create_exchange.md b/docs/docs/cli/corso_backup_create_exchange.md new file mode 100644 index 000000000..3816f6e2c --- /dev/null +++ b/docs/docs/cli/corso_backup_create_exchange.md @@ -0,0 +1,29 @@ +## corso backup create exchange + +Backup M365 Exchange service data + +``` +corso backup create exchange [flags] +``` + +### Options + +``` + --all Backup all Exchange data for all users + --data strings Select one or more types of data to backup: email, contacts, or events + -h, --help help for exchange + --user strings Backup Exchange data by user ID; accepts * to select all users +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso backup create](corso_backup_create.md) - Backup an M365 Service + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_backup_details.md b/docs/docs/cli/corso_backup_details.md new file mode 100644 index 000000000..6f42ae1f3 --- /dev/null +++ b/docs/docs/cli/corso_backup_details.md @@ -0,0 +1,27 @@ +## corso backup details + +Shows the details of a backup for a service + +``` +corso backup details [flags] +``` + +### Options + +``` + -h, --help help for details +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso backup](corso_backup.md) - Backup your service data +* [corso backup details exchange](corso_backup_details_exchange.md) - Shows the details of a M365 Exchange service backup + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_backup_details_exchange.md b/docs/docs/cli/corso_backup_details_exchange.md new file mode 100644 index 000000000..1f66dac22 --- /dev/null +++ b/docs/docs/cli/corso_backup_details_exchange.md @@ -0,0 +1,34 @@ +## corso backup details exchange + +Shows the details of a M365 Exchange service backup + +``` +corso backup details exchange [flags] +``` + +### Options + +``` + --backup string ID of the backup containing the details to be shown + --email strings Select backup details by emails ID; accepts * to select all emails + --email-folder strings Select backup details by email folder ID; accepts * to select all email folderss + --email-received-after string Select backup details where the email was received after this datetime + --email-received-before string Select backup details where the email was received before this datetime + --email-sender string Select backup details where the email sender matches this user id + --email-subject string Select backup details where the email subject lines contain this value + -h, --help help for exchange + --user strings Select backup details by user ID; accepts * to select all users +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso backup details](corso_backup_details.md) - Shows the details of a backup for a service + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_backup_list.md b/docs/docs/cli/corso_backup_list.md new file mode 100644 index 000000000..3cdc1ba95 --- /dev/null +++ b/docs/docs/cli/corso_backup_list.md @@ -0,0 +1,27 @@ +## corso backup list + +List the history of backups for a service + +``` +corso backup list [flags] +``` + +### Options + +``` + -h, --help help for list +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso backup](corso_backup.md) - Backup your service data +* [corso backup list exchange](corso_backup_list_exchange.md) - List the history of M365 Exchange service backups + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_backup_list_exchange.md b/docs/docs/cli/corso_backup_list_exchange.md new file mode 100644 index 000000000..d8b30d8b7 --- /dev/null +++ b/docs/docs/cli/corso_backup_list_exchange.md @@ -0,0 +1,26 @@ +## corso backup list exchange + +List the history of M365 Exchange service backups + +``` +corso backup list exchange [flags] +``` + +### Options + +``` + -h, --help help for exchange +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso backup list](corso_backup_list.md) - List the history of backups for a service + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_repo.md b/docs/docs/cli/corso_repo.md new file mode 100644 index 000000000..e4892b56b --- /dev/null +++ b/docs/docs/cli/corso_repo.md @@ -0,0 +1,32 @@ +## corso repo + +Manage your repositories + +### Synopsis + +Initialize, configure, and connect to your account backup repositories. + +``` +corso repo [flags] +``` + +### Options + +``` + -h, --help help for repo +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso](corso.md) - Protect your Microsoft 365 data. +* [corso repo connect](corso_repo_connect.md) - Connect to a repository. +* [corso repo init](corso_repo_init.md) - Initialize a repository. + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_repo_connect.md b/docs/docs/cli/corso_repo_connect.md new file mode 100644 index 000000000..d1aade143 --- /dev/null +++ b/docs/docs/cli/corso_repo_connect.md @@ -0,0 +1,31 @@ +## corso repo connect + +Connect to a repository. + +### Synopsis + +Connect to an existing repository. + +``` +corso repo connect [flags] +``` + +### Options + +``` + -h, --help help for connect +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso repo](corso_repo.md) - Manage your repositories +* [corso repo connect s3](corso_repo_connect_s3.md) - Connect to a S3 repository + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_repo_connect_s3.md b/docs/docs/cli/corso_repo_connect_s3.md new file mode 100644 index 000000000..864b01721 --- /dev/null +++ b/docs/docs/cli/corso_repo_connect_s3.md @@ -0,0 +1,34 @@ +## corso repo connect s3 + +Connect to a S3 repository + +### Synopsis + +Ensures a connection to an existing S3 repository. + +``` +corso repo connect s3 [flags] +``` + +### Options + +``` + --access-key string Access key ID (replaces the AWS_ACCESS_KEY_ID env variable). + --bucket string Name of the S3 bucket (required). + --endpoint string Server endpoint for S3 communication. (default "s3.amazonaws.com") + -h, --help help for s3 + --prefix string Prefix applied to objects in the bucket. +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso repo connect](corso_repo_connect.md) - Connect to a repository. + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_repo_init.md b/docs/docs/cli/corso_repo_init.md new file mode 100644 index 000000000..f3bcb5898 --- /dev/null +++ b/docs/docs/cli/corso_repo_init.md @@ -0,0 +1,31 @@ +## corso repo init + +Initialize a repository. + +### Synopsis + +Create a new repository to store your backups. + +``` +corso repo init [flags] +``` + +### Options + +``` + -h, --help help for init +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso repo](corso_repo.md) - Manage your repositories +* [corso repo init s3](corso_repo_init_s3.md) - Initialize a S3 repository + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_repo_init_s3.md b/docs/docs/cli/corso_repo_init_s3.md new file mode 100644 index 000000000..e4a77b1bf --- /dev/null +++ b/docs/docs/cli/corso_repo_init_s3.md @@ -0,0 +1,34 @@ +## corso repo init s3 + +Initialize a S3 repository + +### Synopsis + +Bootstraps a new S3 repository and connects it to your m356 account. + +``` +corso repo init s3 [flags] +``` + +### Options + +``` + --access-key string Access key ID (replaces the AWS_ACCESS_KEY_ID env variable). + --bucket string Name of the S3 bucket (required). + --endpoint string Server endpoint for S3 communication. (default "s3.amazonaws.com") + -h, --help help for s3 + --prefix string Prefix applied to objects in the bucket. +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso repo init](corso_repo_init.md) - Initialize a repository. + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_restore.md b/docs/docs/cli/corso_restore.md new file mode 100644 index 000000000..9850d00a0 --- /dev/null +++ b/docs/docs/cli/corso_restore.md @@ -0,0 +1,31 @@ +## corso restore + +Restore your service data + +### Synopsis + +Restore the data stored in one of your M365 services. + +``` +corso restore [flags] +``` + +### Options + +``` + -h, --help help for restore +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso](corso.md) - Protect your Microsoft 365 data. +* [corso restore exchange](corso_restore_exchange.md) - Restore M365 Exchange service data + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/docs/docs/cli/corso_restore_exchange.md b/docs/docs/cli/corso_restore_exchange.md new file mode 100644 index 000000000..a84853c61 --- /dev/null +++ b/docs/docs/cli/corso_restore_exchange.md @@ -0,0 +1,34 @@ +## corso restore exchange + +Restore M365 Exchange service data + +``` +corso restore exchange [flags] +``` + +### Options + +``` + --backup string ID of the backup to restore + --email strings Restore emails by ID; accepts * to select all emails + --email-folder strings Restore all emails by folder ID; accepts * to select all email folders + --email-received-after string Restore mail where the email was received after this datetime + --email-received-before string Restore mail where the email was received before this datetime + --email-sender string Restore mail where the email sender matches this user id + --email-subject string Restore mail where the email subject lines contain this value + -h, --help help for exchange + --user strings Restore all data by user ID; accepts * to select all users +``` + +### Options inherited from parent commands + +``` + --config-file string config file (default is $HOME/.corso) (default "/home/runner/.corso.toml") + --json output data in JSON format +``` + +### SEE ALSO + +* [corso restore](corso_restore.md) - Restore your service data + +###### Auto generated by spf13/cobra on 4-Aug-2022 diff --git a/src/cli/cli.go b/src/cli/cli.go index 26cf5edf9..463747690 100644 --- a/src/cli/cli.go +++ b/src/cli/cli.go @@ -14,6 +14,10 @@ import ( "github.com/alcionai/corso/pkg/logger" ) +// ------------------------------------------------------------------------------------------ +// Corso Command +// ------------------------------------------------------------------------------------------ + // The root-level command. // `corso [] [] [...]` var corsoCmd = &cobra.Command{ @@ -39,20 +43,39 @@ func handleCorsoCmd(cmd *cobra.Command, args []string) error { return cmd.Help() } +// CorsoCommand produces a copy of the cobra command used by Corso. +// The command tree is built and attached to the returned command. +func CorsoCommand() *cobra.Command { + c := &cobra.Command{} + *c = *corsoCmd + BuildCommandTree(c) + return c +} + +// BuildCommandTree builds out the command tree used by the Corso library. +func BuildCommandTree(cmd *cobra.Command) { + cmd.Flags().BoolP("version", "v", version, "current version info") + cmd.PersistentPostRunE = config.InitFunc() + config.AddConfigFileFlag(cmd) + print.AddOutputFlag(cmd) + + cmd.CompletionOptions.DisableDefaultCmd = true + + repo.AddCommands(cmd) + backup.AddCommands(cmd) + restore.AddCommands(cmd) +} + +// ------------------------------------------------------------------------------------------ +// Running Corso +// ------------------------------------------------------------------------------------------ + // Handle builds and executes the cli processor. func Handle() { ctx := config.Seed(context.Background()) - corsoCmd.Flags().BoolP("version", "v", version, "current version info") - config.AddConfigFileFlag(corsoCmd) + BuildCommandTree(corsoCmd) print.SetRootCommand(corsoCmd) - print.AddOutputFlag(corsoCmd) - - corsoCmd.CompletionOptions.DisableDefaultCmd = true - - repo.AddCommands(corsoCmd) - backup.AddCommands(corsoCmd) - restore.AddCommands(corsoCmd) ctx, log := logger.Seed(ctx) defer func() { diff --git a/src/cli/cli_test.go b/src/cli/cli_test.go index ed1641d43..928b6e3dd 100644 --- a/src/cli/cli_test.go +++ b/src/cli/cli_test.go @@ -7,9 +7,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/suite" - "github.com/alcionai/corso/cli/backup" - "github.com/alcionai/corso/cli/repo" - "github.com/alcionai/corso/cli/restore" + "github.com/alcionai/corso/cli" ) type CliSuite struct { @@ -34,7 +32,5 @@ func (suite *CLISuite) TestAddCommands_noPanics() { RunE: func(c *cobra.Command, args []string) error { return nil }, } - assert.NotPanics(t, func() { repo.AddCommands(test) }) - assert.NotPanics(t, func() { backup.AddCommands(test) }) - assert.NotPanics(t, func() { restore.AddCommands(test) }) + assert.NotPanics(t, func() { cli.BuildCommandTree(test) }) } diff --git a/src/cli/repo/s3_integration_test.go b/src/cli/repo/s3_integration_test.go index 86020caae..307e155d9 100644 --- a/src/cli/repo/s3_integration_test.go +++ b/src/cli/repo/s3_integration_test.go @@ -6,11 +6,8 @@ import ( "github.com/stretchr/testify/require" "github.com/stretchr/testify/suite" - "github.com/alcionai/corso/cli/backup" + "github.com/alcionai/corso/cli" "github.com/alcionai/corso/cli/config" - "github.com/alcionai/corso/cli/print" - "github.com/alcionai/corso/cli/repo" - "github.com/alcionai/corso/cli/restore" "github.com/alcionai/corso/internal/tester" ) @@ -62,14 +59,7 @@ func (suite *S3IntegrationSuite) TestInitS3Cmd() { "--config-file", configFP, "--bucket", cfg.Bucket, "--prefix", cfg.Prefix) - cmd.PersistentPostRunE = config.InitFunc() - - // TODO: replace with Build() from in-flight PR #453 - config.AddConfigFileFlag(cmd) - print.AddOutputFlag(cmd) - repo.AddCommands(cmd) - backup.AddCommands(cmd) - restore.AddCommands(cmd) + cli.BuildCommandTree(cmd) // run the command require.NoError(t, cmd.ExecuteContext(ctx)) diff --git a/src/cmd/mdgen/mdgen.go b/src/cmd/mdgen/mdgen.go new file mode 100644 index 000000000..1ee025b0d --- /dev/null +++ b/src/cmd/mdgen/mdgen.go @@ -0,0 +1,80 @@ +package main + +import ( + "fmt" + "os" + "strings" + + "github.com/pkg/errors" + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" + + "github.com/alcionai/corso/cli" +) + +var ( + // generate markdown files in the given. + // callers of this func can then migrate the files + // to where they need. + cliMarkdownDir string +) + +// The root-level command. +// `corso [] [] [...]` +var cmd = &cobra.Command{ + Use: "generate", + Short: "Autogenerate Corso documentation.", + Run: genDocs, +} + +func main() { + cmd. + PersistentFlags(). + StringVar( + &cliMarkdownDir, + "cli-folder", + "./cmd/mdgen/cli_markdown", + "relative path to the folder where cli docs will be generated (default: ./cmd/mdgen/cli_markdown)") + if err := cmd.Execute(); err != nil { + os.Exit(1) + } +} + +func genDocs(cmd *cobra.Command, args []string) { + if err := makeDir(cliMarkdownDir); err != nil { + fatal(errors.Wrap(err, "preparing directory for markdown generation")) + } + err := doc.GenMarkdownTree(cli.CorsoCommand(), cliMarkdownDir) + if err != nil { + fatal(errors.Wrap(err, "generating the Corso CLI markdown")) + } +} + +func makeDir(dir string) error { + wd, err := os.Getwd() + if err != nil { + return errors.Wrap(err, "finding current working directory") + } + + if !strings.HasSuffix(wd, "/src") { + return errors.New("must be called from /corso/src") + } + + _, err = os.Stat(dir) + if err != nil && !errors.Is(err, os.ErrNotExist) { + return errors.Wrap(err, "unable to discover directory") + } + + if errors.Is(err, os.ErrNotExist) { + if err := os.Mkdir(dir, os.ModePerm); err != nil { + return errors.Wrap(err, "generating directory to hold markdown") + } + } + + return nil +} + +func fatal(err error) { + fmt.Fprintf(os.Stderr, "ERR: %v\n", err) + os.Exit(1) +} diff --git a/src/go.mod b/src/go.mod index 003657d1a..4708e0a83 100644 --- a/src/go.mod +++ b/src/go.mod @@ -45,6 +45,7 @@ require ( github.com/cespare/xxhash/v2 v2.1.2 // indirect github.com/chmduquesne/rollinghash v4.0.0+incompatible // indirect github.com/cjlapao/common-go v0.0.22 // indirect + github.com/cpuguy83/go-md2man/v2 v2.0.1 // indirect github.com/davecgh/go-spew v1.1.1 // indirect github.com/dustin/go-humanize v1.0.0 // indirect github.com/edsrzf/mmap-go v1.1.0 // indirect @@ -83,6 +84,7 @@ require ( github.com/prometheus/procfs v0.7.3 // indirect github.com/rivo/uniseg v0.2.0 // indirect github.com/rs/xid v1.4.0 // indirect + github.com/russross/blackfriday/v2 v2.1.0 // indirect github.com/sirupsen/logrus v1.8.1 // indirect github.com/yosida95/uritemplate/v3 v3.0.2 // indirect github.com/zeebo/blake3 v0.2.3 // indirect diff --git a/src/go.sum b/src/go.sum index 50da42750..ef92f75f9 100644 --- a/src/go.sum +++ b/src/go.sum @@ -79,6 +79,7 @@ github.com/cncf/udpa/go v0.0.0-20210930031921-04548b0d99d4/go.mod h1:6pvJx4me5XP github.com/cncf/xds/go v0.0.0-20210922020428-25de7278fc84/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs= github.com/cncf/xds/go v0.0.0-20211001041855-01bcc9b48dfe/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs= github.com/cncf/xds/go v0.0.0-20211011173535-cb28da3451f1/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs= +github.com/cpuguy83/go-md2man/v2 v2.0.1 h1:r/myEWzV9lfsM1tFLgDyu0atFtJ1fXn261LKYj/3DxU= github.com/cpuguy83/go-md2man/v2 v2.0.1/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= @@ -330,6 +331,7 @@ github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFR github.com/rogpeppe/go-internal v1.6.1 h1:/FiVV8dS/e+YqF2JvO3yXRFbBLTIuSDkuC7aBOAvL+k= github.com/rs/xid v1.4.0 h1:qd7wPTDkN6KQx2VmMBLrpHkiyQwgFXRnkOLacUiaSNY= github.com/rs/xid v1.4.0/go.mod h1:trrq9SKmegXys3aeAKXMUTdJsYXVwGY3RLcfgqegfbg= +github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/sirupsen/logrus v1.2.0/go.mod h1:LxeOpSwHxABJmUn/MG1IvRgCAasNZTLOkJPxbbu5VWo= github.com/sirupsen/logrus v1.4.2/go.mod h1:tLMulIdttU9McNUspp0xgXVQah82FyeX6MwdIuYE2rE=