diff --git a/.gitignore b/.gitignore index 1fe982e7e84162b135ca765fbc7fe820cc121d71..8b976c1d9262ff7da6690fb1dcef65193f283b78 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,9 @@ /bin .envrc +# asdf +.tool-versions + # man pages /share/man/man1 diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 6676b04d0c7c401d87852f65a571292ba3d32036..601aa1c2fe10eaeb2e8ef4af0057c0210026affa 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -16,6 +16,7 @@ default: image: golang:1.18 stages: + - review-docs - test - release @@ -27,6 +28,18 @@ include: - template: Security/Dependency-Scanning.gitlab-ci.yml - template: Security/Secret-Detection.gitlab-ci.yml +check_docs_markdown: + image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.16-vale-2.20.1-markdownlint-0.32.2 + stage: review-docs + cache: {} + dependencies: [] + before_script: [] + script: + # Lint prose + - vale --minAlertLevel error docs + # Lint Markdown + - markdownlint --config .markdownlint.yml 'docs/**/*.md' + code_navigation: stage: test image: golang:latest diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 0000000000000000000000000000000000000000..2ad24e5f754548a6297736ea9db93a3b08d08972 --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,151 @@ +--- +# Base Markdownlint configuration +# Extended Markdownlint configuration in doc/.markdownlint/ +default: true +first-header-h1: true +header-style: + style: "atx" +ul-style: + style: "dash" +no-trailing-spaces: false +line-length: false +no-duplicate-header: + allow_different_nesting: true +no-trailing-punctuation: + punctuation: ".,;:!。，；：！？" +ol-prefix: + style: "one" +no-inline-html: false +hr-style: + style: "---" +no-emphasis-as-heading: false +first-line-h1: false +code-block-style: + style: "fenced" +emphasis-style: false +link-fragments: false +reference-links-images: false +proper-names: + names: [ + "Akismet", + "Alertmanager", + "AlmaLinux", + "API", + "Asana", + "Auth0", + "Authentiq", + "Azure", + "Bamboo", + "Bitbucket", + "Bugzilla", + "CAS", + "CentOS", + "Consul", + "Debian", + "DevOps", + "Docker", + "DockerSlim", + "Elasticsearch", + "Facebook", + "fastlane", + "fluent-plugin-redis-slowlog", + "GDK", + "Geo", + "Git LFS", + "git-annex", + "git-sizer", + "Git", + "Gitaly", + "GitHub", + "GitLab Geo", + "GitLab Monitor", + "GitLab Operator", + "GitLab Pages", + "GitLab Rails", + "GitLab Runner", + "GitLab Shell", + "GitLab Workhorse", + "GitLab", + "Gitleaks", + "Gmail", + "Google", + "Grafana", + "Gzip", + "Helm", + "HipChat", + "ID", + "Ingress", + "jasmine-jquery", + "JavaScript", + "Jaeger", + "Jenkins", + "Jira", + "Jira Cloud", + "Jira Server", + "jQuery", + "JSON", + "JupyterHub", + "Karma", + "Kerberos", + "Knative", + "Kubernetes", + "LDAP", + "Let's Encrypt", + "Markdown", + "markdownlint", + "Mattermost", + "Microsoft", + "minikube", + "MinIO", + "ModSecurity", + "NGINX Ingress", + "NGINX", + "OAuth", + "OAuth 2", + "OmniAuth", + "Omnibus GitLab", + "OpenID", + "OpenShift", + "PgBouncer", + "Postfix", + "PostgreSQL", + "Praefect", + "Prometheus", + "Puma", + "puma-worker-killer", + "Python", + "Rake", + "Redis", + "Redmine", + "reCAPTCHA", + "Ruby", + "runit", + "Salesforce", + "SAML", + "Sendmail", + "Sentry", + "Service Desk", + "Sidekiq", + "Shibboleth", + "Slack", + "SMTP", + "SpotBugs", + "SSH", + "Tiller", + "TOML", + "Trello", + "Trello Power-Ups", + "TypeScript", + "Twitter", + "Ubuntu", + "Ultra Auth", + "Unicorn", + "unicorn-worker-killer", + "URL", + "WebdriverIO", + "Workload Identity Pool", + "Workload Identity Provider", + "YAML", + "YouTrack" + ] + code_blocks: false diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000000000000000000000000000000000000..c60ecc45335579ecdf37764dde589036f6b85fc9 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,12 @@ +# Vale configuration file. +# +# For more information, see https://errata-ai.gitbook.io/vale/getting-started/configuration. + +StylesPath = docs/.vale +MinAlertLevel = suggestion + +[*.md] +BasedOnStyles = gitlab + +# Ignore SVG markup +TokenIgnores = (\*\*\{\w*\}\*\*) diff --git a/cmd/gen-docs/docs.go b/cmd/gen-docs/docs.go index 62c48b55b9d8df16cf78088944a0388f26e43093..a669a1f597765a53da3ec1bea2b8de934f8a36ac 100644 --- a/cmd/gen-docs/docs.go +++ b/cmd/gen-docs/docs.go @@ -17,7 +17,6 @@ import ( "gitlab.com/gitlab-org/cli/commands" "gitlab.com/gitlab-org/cli/commands/cmdutils" "gitlab.com/gitlab-org/cli/internal/config" - "gitlab.com/gitlab-org/cli/pkg/utils" ) var tocTree = `.. toctree:: @@ -88,20 +87,20 @@ func genWebDocs(glabCli *cobra.Command, path string) error { // Generate parent command out := new(bytes.Buffer) - err := GenReSTCustom(cmd, out) + err := GenMarkdownCustom(cmd, out) if err != nil { return err } // Generate children commands for _, cmdC := range cmd.Commands() { - err = GenReSTTreeCustom(cmdC, path+cmd.Name()) + err = GenMarkdownTreeCustom(cmdC, path+cmd.Name()) if err != nil { return err } } - err = config.WriteFile(path+cmd.Name()+"/index.rst", out.Bytes(), 0755) + err = config.WriteFile(path+cmd.Name()+"/index.md", out.Bytes(), 0755) if err != nil { return err } @@ -114,23 +113,16 @@ func printSubcommands(cmd *cobra.Command, buf *bytes.Buffer) { return } - var tree string + var subcommands string // Generate children commands for _, cmdC := range cmd.Commands() { if cmdC.Name() != "help" { - tree += fmt.Sprintf("%s <%s>\n", cmdC.Name(), cmdC.Name()) + subcommands += fmt.Sprintf("- [%s](%s.md)\n", cmdC.Name(), cmdC.Name()) } } - subcommands := "" - if tree != "" { - tree = utils.Indent(tree, " ") - subcommands = fmt.Sprintf(tocTree, tree) - } - if subcommands != "" { - buf.WriteString("Subcommands\n") - buf.WriteString("~~~~~~~~~~~\n") + buf.WriteString("### Subcommands\n\n") buf.WriteString(subcommands) buf.WriteString("\n") } @@ -141,21 +133,20 @@ func fatal(err error) { os.Exit(1) } -// adapted from : github.com/spf13/cobra/doc/rest_docs.go - -// GenReSTTreeCustom is the the same as GenReSTTree, but +// adapted from : github.com/spf13/cobra/blob/main/doc/md_docs.go +// GenMarkdownTreeCustom is the the same as GenMarkdownTree, but // with custom filePrepender and linkHandler. -func GenReSTTreeCustom(cmd *cobra.Command, dir string) error { +func GenMarkdownTreeCustom(cmd *cobra.Command, dir string) error { for _, c := range cmd.Commands() { if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() { continue } - if err := GenReSTTreeCustom(c, dir); err != nil { + if err := GenMarkdownTreeCustom(c, dir); err != nil { return err } } - basename := cmd.Name() + ".rst" + basename := strings.ReplaceAll(cmd.Name(), " ", "_") + ".md" filename := filepath.Join(dir, basename) f, err := os.Create(filename) if err != nil { @@ -163,73 +154,62 @@ func GenReSTTreeCustom(cmd *cobra.Command, dir string) error { } defer f.Close() - if err := GenReSTCustom(cmd, f); err != nil { + if err := GenMarkdownCustom(cmd, f); err != nil { return err } return nil } -// GenReSTCustom creates custom reStructured Text output. -func GenReSTCustom(cmd *cobra.Command, w io.Writer) error { +// GenMarkdownCustom creates custom Markdown output. github.com/spf13/cobra/blob/main/doc/md_docs.go +func GenMarkdownCustom(cmd *cobra.Command, w io.Writer) error { cmd.InitDefaultHelpCmd() cmd.InitDefaultHelpFlag() buf := new(bytes.Buffer) name := cmd.CommandPath() - short := cmd.Short - long := cmd.Long - if long == "" { - long = short + buf.WriteString("## " + name + "\n\n") + buf.WriteString(cmd.Short + "\n\n") + if len(cmd.Long) > 0 { + buf.WriteString("### Synopsis\n\n") + buf.WriteString(cmd.Long + "\n\n") } - ref := strings.ReplaceAll(name, " ", "_") - - buf.WriteString(".. _" + ref + ":\n\n") - buf.WriteString(name + "\n") - buf.WriteString(strings.Repeat("-", len(name)) + "\n\n") - buf.WriteString(short + "\n\n") - buf.WriteString("Synopsis\n") - buf.WriteString("~~~~~~~~\n\n") - buf.WriteString("\n" + long + "\n\n") if cmd.Runnable() { - buf.WriteString(fmt.Sprintf("::\n\n %s\n\n", cmd.UseLine())) + buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine())) } if len(cmd.Example) > 0 { - buf.WriteString("Examples\n") - buf.WriteString("~~~~~~~~\n\n") - buf.WriteString(fmt.Sprintf("::\n\n%s\n\n", utils.Indent(cmd.Example, " "))) + buf.WriteString("### Examples\n\n") + buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example)) } - if err := printOptionsReST(buf, cmd, name); err != nil { + if err := printOptions(buf, cmd, name); err != nil { return err } printSubcommands(cmd, buf) - + _, err := buf.WriteTo(w) return err } -// adapted from : github.com/spf13/cobra/doc/rest_docs.go -func printOptionsReST(buf *bytes.Buffer, cmd *cobra.Command, name string) error { +// adapted from : github.com/spf13/cobra/blob/main/doc/md_docs.go +func printOptions(buf *bytes.Buffer, cmd *cobra.Command, name string) error { flags := cmd.NonInheritedFlags() flags.SetOutput(buf) if flags.HasAvailableFlags() { - buf.WriteString("Options\n") - buf.WriteString("~~~~~~~\n\n::\n\n") + buf.WriteString("### Options\n\n```\n") flags.PrintDefaults() - buf.WriteString("\n") + buf.WriteString("```\n\n") } parentFlags := cmd.InheritedFlags() parentFlags.SetOutput(buf) if parentFlags.HasAvailableFlags() { - buf.WriteString("Options inherited from parent commands\n") - buf.WriteString("~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n") + buf.WriteString("### Options inherited from parent commands\n\n```\n") parentFlags.PrintDefaults() - buf.WriteString("\n") + buf.WriteString("```\n\n") } return nil } diff --git a/commands/version/version.go b/commands/version/version.go index 7c8d82e5e814a63bb109c812ac5de7c5811ce041..c72bcf6754637d66bad00884f5b36adaec71a0cf 100644 --- a/commands/version/version.go +++ b/commands/version/version.go @@ -12,7 +12,7 @@ import ( func NewCmdVersion(s *iostreams.IOStreams, version, buildDate string) *cobra.Command { var versionCmd = &cobra.Command{ Use: "version", - Short: "show glab version information", + Short: "Show glab version information", Long: ``, Aliases: []string{"v"}, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/docs/.markdownlint/markdownlint-no-trailing-spaces.yml b/docs/.markdownlint/markdownlint-no-trailing-spaces.yml new file mode 100644 index 0000000000000000000000000000000000000000..8720fbafcb30e27543e578e933c814b1251421e2 --- /dev/null +++ b/docs/.markdownlint/markdownlint-no-trailing-spaces.yml @@ -0,0 +1,4 @@ +--- +# Extended Markdown configuration to enforce no-trailing-spaces rule +extends: "../../.markdownlint.yml" +no-trailing-spaces: true diff --git a/docs/.vale/gitlab/Admin.yml b/docs/.vale/gitlab/Admin.yml new file mode 100644 index 0000000000000000000000000000000000000000..78a86e274561af368bd79bedb5f8cc693ced9f03 --- /dev/null +++ b/docs/.vale/gitlab/Admin.yml @@ -0,0 +1,13 @@ +--- +# Suggestion: gitlab.Admin +# +# Checks for "admin" and recommends using the full word instead. "Admin Area" is OK. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Verify this use of the word "admin". Can it be updated to "administration", "administrator", "administer", or "Admin Area"?' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html +level: suggestion +ignorecase: false +swap: + '[Aa]dmin ?\w*': '(?:Admin( Area| Mode)?|[Aa]dminist(ration|rator|rators|er|rative|ering|ered))' diff --git a/docs/.vale/gitlab/AlertBoxStyle.yml b/docs/.vale/gitlab/AlertBoxStyle.yml new file mode 100644 index 0000000000000000000000000000000000000000..5912c4707fd93d86327e95f153b5671f55e5f6e1 --- /dev/null +++ b/docs/.vale/gitlab/AlertBoxStyle.yml @@ -0,0 +1,20 @@ +--- +# Error: gitlab.AlertBoxStyle +# +# Makes sure alert boxes are used with block quotes. Checks for 3 formatting issues: +# +# - Alert boxes inside a block quote (">") +# - Alert boxes with the note text on the same line +# - Alert boxes using words other than "NOTE" or "WARNING" +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Alert box "%s" must use the formatting in the style guide.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#alert-boxes +level: error +nonword: true +scope: raw +raw: + - '(\n *\> *(?:NOTE|WARNING)|' + - '\n\n(NOTE|WARNING):[^\n]|' + - '\n\n *(?:> )?\**(Note|note|TIP|Tip|tip|CAUTION|Caution|caution|DANGER|Danger|danger|Warning|warning):.*)' diff --git a/docs/.vale/gitlab/BadPlurals.yml b/docs/.vale/gitlab/BadPlurals.yml new file mode 100644 index 0000000000000000000000000000000000000000..533805c67b089bd8bf2237d17cc7146a54d7fa7a --- /dev/null +++ b/docs/.vale/gitlab/BadPlurals.yml @@ -0,0 +1,13 @@ +--- +# Warning: gitlab.BadPlurals +# +# Don't write plural words with the '(s)' construction. "HTTP(S)" is acceptable. +# +# For a list of all options, see https://docs.errata.ai/vale/styles +extends: existence +message: 'Rewrite "%s" to be plural, without parentheses.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#s +level: warning +ignorecase: true +raw: + - '\b\w+\(s\)(?>>>>>> .+\n' diff --git a/docs/.vale/gitlab/MultiLineLinks.yml b/docs/.vale/gitlab/MultiLineLinks.yml new file mode 100644 index 0000000000000000000000000000000000000000..64ad017f16c03a78429128708faf28635da2c6cf --- /dev/null +++ b/docs/.vale/gitlab/MultiLineLinks.yml @@ -0,0 +1,14 @@ +--- +# Error: gitlab.MultiLineLinks +# +# Checks that links are all on a single line. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Link "%s" must be on a single line, even if very long.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#basic-link-criteria +level: error +scope: raw +raw: + - '\[[^\[\]]*?\n[^\[\]]*?\]\([^\)]*?\)|' + - '\[[^\[\]]*?\]\([^\)]*?\n[^\)]*\)' diff --git a/docs/.vale/gitlab/NonStandardQuotes.yml b/docs/.vale/gitlab/NonStandardQuotes.yml new file mode 100644 index 0000000000000000000000000000000000000000..f31d615eb19afcaba24ae27ced9388c68a761ecd --- /dev/null +++ b/docs/.vale/gitlab/NonStandardQuotes.yml @@ -0,0 +1,14 @@ +--- +# Warning: gitlab.NonStandardQuotes +# +# Use only standard single and double quotes, not left or right quotes. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Use standard single quotes or double quotes only. Do not use left or right quotes.' +level: warning +ignorecase: true +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html +scope: raw +raw: + - '[‘’“”]' diff --git a/docs/.vale/gitlab/OutdatedVersions.yml b/docs/.vale/gitlab/OutdatedVersions.yml new file mode 100644 index 0000000000000000000000000000000000000000..f25de44ad177cc6fbd778dcb1f26ad4fb5b7fa94 --- /dev/null +++ b/docs/.vale/gitlab/OutdatedVersions.yml @@ -0,0 +1,24 @@ +--- +# Suggestion: gitlab.OutdatedVersions +# +# Checks for references to versions of GitLab that are no longer supported. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Can this reference to "%s" be refactored?' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#gitlab-versions +level: suggestion +nonword: true +ignorecase: true +tokens: + - "GitLab (v)?2." + - "GitLab (v)?3." + - "GitLab (v)?4." + - "GitLab (v)?5." + - "GitLab (v)?6." + - "GitLab (v)?7." + - "GitLab (v)?8." + - "GitLab (v)?9." + - "GitLab (v)?10." + - "GitLab (v)?11." + - "GitLab (v)?12." diff --git a/docs/.vale/gitlab/OxfordComma.yml b/docs/.vale/gitlab/OxfordComma.yml new file mode 100644 index 0000000000000000000000000000000000000000..1716145b26a2324aa6bcfc6a80c689703fe4a19d --- /dev/null +++ b/docs/.vale/gitlab/OxfordComma.yml @@ -0,0 +1,12 @@ +--- +# Warning: gitlab.OxfordComma +# +# Checks for the lack of an Oxford comma. In some cases, will catch overly complex sentence structures with lots of commas. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Use a comma before the last "and" or "or" in a list of four or more items.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation +level: warning +raw: + - '(?:[\w-_` ]+,){2,}(?:[\w-_` ]+) (and |or )' diff --git a/docs/.vale/gitlab/Possessive.yml b/docs/.vale/gitlab/Possessive.yml new file mode 100644 index 0000000000000000000000000000000000000000..92ae66543a250162e33ae2720af839fd5af491dc --- /dev/null +++ b/docs/.vale/gitlab/Possessive.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.Possessive +# +# The word GitLab should not be used in the possessive form. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: "Rewrite '%s' to not use 's." +level: error +ignorecase: true +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#trademark +tokens: + - GitLab's diff --git a/docs/.vale/gitlab/ReadingLevel.yml b/docs/.vale/gitlab/ReadingLevel.yml new file mode 100644 index 0000000000000000000000000000000000000000..cd7597ee8dc51cf0629b110e6729a9128905fa47 --- /dev/null +++ b/docs/.vale/gitlab/ReadingLevel.yml @@ -0,0 +1,13 @@ +--- +# Suggestion: gitlab.ReadingLevel +# +# Checks the Flesch-Kincaid reading level. +# +# https://docs.errata.ai/vale/styles#metric +extends: metric +message: "The grade level - %s - refers to how hard the content is to understand. Aim for 8th grade or lower by using shorter sentences and words." +link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-readability-score +level: suggestion +formula: | + (0.39 * (words / sentences)) + (11.8 * (syllables / words)) - 15.59 +condition: "> 1" diff --git a/docs/.vale/gitlab/ReferenceLinks.yml b/docs/.vale/gitlab/ReferenceLinks.yml new file mode 100644 index 0000000000000000000000000000000000000000..ca9948844f857a2a62f854d26f3c8a8f7e11e1c8 --- /dev/null +++ b/docs/.vale/gitlab/ReferenceLinks.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.ReferenceLinks +# +# Checks for reference-style links that should be converted to inline links. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Link "%s" must be inline.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#basic-link-criteria +level: error +scope: raw +raw: + - '\n\[[^\]]*\]: .*' diff --git a/docs/.vale/gitlab/RelativeLinks.yml b/docs/.vale/gitlab/RelativeLinks.yml new file mode 100644 index 0000000000000000000000000000000000000000..14ffc4bd0b83da89a6168afc801c1da34331db80 --- /dev/null +++ b/docs/.vale/gitlab/RelativeLinks.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.RelativeLinks +# +# Checks for the presence of absolute hyperlinks that should be relative. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Link "%s" must be a relative link with a .md extension.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation +level: error +scope: raw +raw: + - '\[.+\]\(https?:\/\/docs\.gitlab\.com\/[ce]e.*\)' diff --git a/docs/.vale/gitlab/RelativeLinksDoubleSlashes.yml b/docs/.vale/gitlab/RelativeLinksDoubleSlashes.yml new file mode 100644 index 0000000000000000000000000000000000000000..ce6ce8b5691853e58772ad06deb8a218043d2a36 --- /dev/null +++ b/docs/.vale/gitlab/RelativeLinksDoubleSlashes.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.RelativeLinksDoubleSlashes +# +# Checks for the presence of double slashes in relative URLs. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Relative links must not include a double slash.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation +level: error +scope: raw +raw: + - '\.//' diff --git a/docs/.vale/gitlab/Repetition.yml b/docs/.vale/gitlab/Repetition.yml new file mode 100644 index 0000000000000000000000000000000000000000..c4b0cc1419284fd0ced9b50a5ab72d00bc60a8d9 --- /dev/null +++ b/docs/.vale/gitlab/Repetition.yml @@ -0,0 +1,12 @@ +--- +# Error: gitlab.Repetition +# +# Checks for duplicate words, like `the the` or `and and`. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: repetition +message: '"%s" is repeated.' +level: error +alpha: true +tokens: + - '[^\s]+' diff --git a/docs/.vale/gitlab/SentenceLength.yml b/docs/.vale/gitlab/SentenceLength.yml new file mode 100644 index 0000000000000000000000000000000000000000..c60df1803e2df4a8c253cb3ba513b0b5fecc3a6b --- /dev/null +++ b/docs/.vale/gitlab/SentenceLength.yml @@ -0,0 +1,13 @@ +--- +# Warning: gitlab.SentenceLength +# +# Counts words in a sentence and alerts if a sentence exceeds 25 words. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: occurrence +message: 'Shorter sentences improve readability (max 25 words).' +scope: sentence +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language +level: warning +max: 25 +token: \b(\w+)\b diff --git a/docs/.vale/gitlab/SentenceSpacing.yml b/docs/.vale/gitlab/SentenceSpacing.yml new file mode 100644 index 0000000000000000000000000000000000000000..0288abe834ffbc6e69fc9fc6318e838ed2d18246 --- /dev/null +++ b/docs/.vale/gitlab/SentenceSpacing.yml @@ -0,0 +1,14 @@ +--- +# Error: gitlab.SentenceSpacing +# +# Checks for incorrect spacing (no spaces, or more than one space) around punctuation. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: '"%s" must contain one and only one space.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation +level: error +nonword: true +tokens: + - '[a-z][.?!,][A-Z]' + - '[\w.?!,\(\)\-":] {2,}[\w.?!,\(\)\-":]' diff --git a/docs/.vale/gitlab/Simplicity.yml b/docs/.vale/gitlab/Simplicity.yml new file mode 100644 index 0000000000000000000000000000000000000000..44e78f89c20f7f279d159ec3e56f0ed06a1edcdf --- /dev/null +++ b/docs/.vale/gitlab/Simplicity.yml @@ -0,0 +1,18 @@ +--- +# Suggestion: gitlab.Simplicity +# +# Checks for words implying ease of use, to avoid cognitive dissonance for frustrated users. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.' +level: suggestion +ignorecase: true +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list +tokens: + - easy + - easily + - handy + - simple + - simply + - useful diff --git a/docs/.vale/gitlab/Spelling.yml b/docs/.vale/gitlab/Spelling.yml new file mode 100644 index 0000000000000000000000000000000000000000..4ebaf7bfb70c49c46c8ae591e61e5096b21b714d --- /dev/null +++ b/docs/.vale/gitlab/Spelling.yml @@ -0,0 +1,16 @@ +--- +# Warning: gitlab.Spelling +# +# Checks for possible spelling mistakes in content, not code. Results from links using angle brackets () should be corrected. +# +# If a word is flagged as a spelling mistake incorrectly, such as a product name, +# you can submit an MR to update `spelling-exceptions.txt` with the missing word. +# Commands, like `git clone` must use backticks, and must not be added to the +# exceptions. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: spelling +message: 'Spelling check: "%s"?' +level: warning +ignore: + - gitlab/spelling-exceptions.txt diff --git a/docs/.vale/gitlab/SubstitutionSuggestions.yml b/docs/.vale/gitlab/SubstitutionSuggestions.yml new file mode 100644 index 0000000000000000000000000000000000000000..4b77def065d255e8368a0aa961ceebd746e3d28a --- /dev/null +++ b/docs/.vale/gitlab/SubstitutionSuggestions.yml @@ -0,0 +1,28 @@ +--- +# Suggestion: gitlab.SubstitutionSuggestions +# +# Suggests better options for frequently misused terms that are often - but not always - incorrect. +# SubstitutionWarning.yml and Substitutions.yml also exist. +# +# For a list of all options, see https://errata-ai.github.io/vale/styles/ +extends: substitution +message: 'Consider %s instead of "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html +level: suggestion +ignorecase: true +swap: + active user: '"billable user"' + active users: '"billable users"' + docs: '"documentation"' + e-mail: '"email"' + GLFM: '"GitLab Flavored Markdown"' + it is recommended: '"we recommend"' + navigate: go + OAuth2: '"OAuth 2.0"' + once that: '"after that"' + once the: '"after the"' + once you: '"after you"' + since: '"because" or "after"' + sub-group: '"subgroup"' + sub-groups: '"subgroups"' + within: '"in"' diff --git a/docs/.vale/gitlab/SubstitutionWarning.yml b/docs/.vale/gitlab/SubstitutionWarning.yml new file mode 100644 index 0000000000000000000000000000000000000000..d17015b97fd20c875ececaea0ac9546700d191ea --- /dev/null +++ b/docs/.vale/gitlab/SubstitutionWarning.yml @@ -0,0 +1,29 @@ +--- +# Warning: gitlab.SubstitutionWarning +# +# Checks for misused terms or common shorthand that should never be used at GitLab, but can't be flagged as errors. +# Substitutions.yml and SubstitionSuggestions.yml also exist. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'If possible, use "%s" instead of "%s".' +link: https://about.gitlab.com/handbook/communication/#top-misused-terms +level: warning +ignorecase: true +swap: + air(?:-| )?gapped: offline environment + bullet: list item + click: select + code base: codebase + config: configuration + deselect: clear + deselected: cleared + distro: distribution + file name: filename + filesystem: file system + GFM: GLFM + info: information + n/a: not applicable + repo: repository + timezone: time zone + utilize: use diff --git a/docs/.vale/gitlab/Substitutions.yml b/docs/.vale/gitlab/Substitutions.yml new file mode 100644 index 0000000000000000000000000000000000000000..af426fa7e061e2f12dc8e3ce4f86f328d9d5dc7d --- /dev/null +++ b/docs/.vale/gitlab/Substitutions.yml @@ -0,0 +1,62 @@ +--- +# Error: gitlab.Substitutions +# +# Checks for misused terms that should never be used at GitLab. +# SubstitutionWarning.yml and SubstitionSuggestions.yml also exist. +# +# For a list of all options, see https://docs.errata.ai/vale/styles +extends: substitution +message: 'Use "%s" instead of "%s".' +link: https://about.gitlab.com/handbook/communication/#top-misused-terms +level: error +ignorecase: true +swap: + codequality: code quality + Customer [Pp]ortal: Customers Portal + disallow: prevent + frontmatter: front matter + GitLabber: GitLab team member + GitLabbers: GitLab team members + GitLab-shell: GitLab Shell + gitlab omnibus: Omnibus GitLab + param: parameter + params: parameters + pg: PostgreSQL + 'postgres$': PostgreSQL + raketask: Rake task + raketasks: Rake tasks + rspec: RSpec + self hosted: self-managed + self-hosted: self-managed + styleguide: style guide + to login: to log in + can login: can log in + to log-in: to log in + can log-in: can log in + to signin: to sign in + can signin: can sign in + to sign-in: to sign in + can sign-in: can sign in + x509: X.509 + yml: YAML + admin user: administrator + admin users: administrators + administrator permission: administrator access + administrator permissions: administrator access + administrator role: administrator access + the administrator access level: administrator access + developer access: the Developer role + developer permission: the Developer role + developer permissions: the Developer role + guest access: the Guest role + guest permission: the Guest role + guest permissions: the Guest role + maintainer access: the Maintainer role + maintainer permission: the Maintainer role + maintainer permissions: the Maintainer role + owner access: the Owner role + owner permission: the Owner role + owner permissions: the Owner role + reporter access: the Reporter role + reporter permission: the Reporter role + reporter permissions: the Reporter role diff --git a/docs/.vale/gitlab/ToDo.yml b/docs/.vale/gitlab/ToDo.yml new file mode 100644 index 0000000000000000000000000000000000000000..a3725cb7f6bf46c979deb0779f3dda560f827ae2 --- /dev/null +++ b/docs/.vale/gitlab/ToDo.yml @@ -0,0 +1,14 @@ +--- +# Warning: gitlab.ToDo +# +# You should not use "To Do", unless it refers to the UI element. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: substitution +message: 'Use "to-do item" in most cases, or "Add a to do" if referring to the UI button.' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#feature-names +level: warning +ignorecase: false +swap: + '[Tt]o [Dd]o [Ii]tems?': to-do item + '\w* [Aa] [Tt]o [Dd]o': Add a to do diff --git a/docs/.vale/gitlab/UnclearAntecedent.yml b/docs/.vale/gitlab/UnclearAntecedent.yml new file mode 100644 index 0000000000000000000000000000000000000000..5f238598d9f1a4f40b73152f865cb6ff38292fd9 --- /dev/null +++ b/docs/.vale/gitlab/UnclearAntecedent.yml @@ -0,0 +1,22 @@ +--- +# Warning: gitlab.UnclearAntecedent +# +# Checks for words that need a noun for clarity. +# +# For a list of all options, see https://docs.errata.ai/vale/styles +extends: existence +message: "'%s' is not precise. Try rewriting with a specific subject and verb." +link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#this-these-that-those +level: warning +ignorecase: false +tokens: + - 'That is' + - 'That was' + - 'These are' + - 'These were' + - 'There are' + - 'There were' + - 'This is' + - 'This was' + - 'Those are' + - 'Those were' diff --git a/docs/.vale/gitlab/Uppercase.yml b/docs/.vale/gitlab/Uppercase.yml new file mode 100644 index 0000000000000000000000000000000000000000..dc05aa05730a735c3ef27073f3ace91500bb6c6d --- /dev/null +++ b/docs/.vale/gitlab/Uppercase.yml @@ -0,0 +1,252 @@ +--- +# Warning: gitlab.Uppercase +# +# Checks for use of all uppercase letters with unknown reason. +# +# For a list of all options, see https://docs.errata.ai/vale/styles. +extends: conditional +message: "'%s' is uppercase. Use lowercase or `backticks` if possible. Otherwise add this word to the rule's exception list." +link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-uppercase-acronym-test +level: warning +ignorecase: false +# Ensures that the existence of 'first' implies the existence of 'second'. +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - ACL + - AJAX + - AMI + - ANSI + - APAC + - API + - APM + - ARM + - ARN + - ASCII + - ASG + - AWS + - BMP + - BSD + - CAS + - CDN + - CGI + - CIDR + - CLI + - CNA + - CNCF + - CORE + - CORS + - CPU + - CRIME + - CRM + - CRUD + - CSRF + - CSS + - CSV + - CTE + - CWE + - CVE + - CVS + - CVSS + - DAG + - DAST + - DDL + - DHCP + - DML + - DNS + - DOM + - DORA + - DSA + - DSL + - DVCS + - DVD + - EBS + - ECDSA + - ECS + - EFS + - EKS + - ELB + - ENA + - EOL + - EWM + - EXIF + - FAQ + - FIDO + - FIFO + - FIPS + - FLAG + - FOSS + - FQDN + - FREE + - FTP + - GCP + - GDK + - GDPR + - GET + - GID + - GIF + - GKE + - GLEX + - GLFM + - GNU + - GPG + - GPL + - GPS + - GPT + - GPU + - GUI + - HAML + - HDD + - HEAD + - HIPAA + - HLL + - HSTS + - HTML + - HTTP + - HTTPS + - IAM + - IANA + - IBM + - ICO + - IDE + - IID + - IIS + - IMAP + - IOPS + - IRC + - ISO + - JPEG + - JPG + - JSON + - JVM + - JWT + - KICS + - LAN + - LDAP + - LDAPS + - LESS + - LFS + - LRU + - LSIF + - LTM + - LTS + - LVM + - MIME + - MIT + - MITRE + - MVC + - NAS + - NAT + - NDA + - NFS + - NGINX + - NOTE + - NPM + - NTP + - OKD + - ONLY + - OSS + - OTP + - OWASP + - PAT + - PCI-DSS + - PDF + - PEM + - PEP + - PGP + - PHP + - PID + - PKCS + - PNG + - POSIX + - POST + - PROXY + - PUT + - QPS + - RAID + - RAM + - RBAC + - RDP + - RDS + - RDS + - REST + - RFC + - RHEL + - RPC + - RPM + - RPS + - RSA + - RSS + - RTC + - RVM + - SAAS + - SAML + - SAN + - SAST + - SATA + - SBOM + - SCIM + - SCM + - SCP + - SCSS + - SDK + - SELF + - SEO + - SFTP + - SHA + - SKI + - SLA + - SLI + - SLO + - SMS + - SMTP + - SOAP + - SOC + - SOX + - SPDX + - SPDY + - SPF + - SQL + - SRE + - SSD + - SSG + - SSH + - SSL + - SSO + - STI + - SUSE + - SVG + - SVN + - TCP + - TIFF + - TIP + - TLD + - TLS + - TODO + - TOML + - TOTP + - TPS + - TTL + - UBI + - UDP + - UID + - UID + - UNIX + - URI + - URL + - USB + - UTC + - UTF + - UUID + - VCS + - VPC + - VPN + - WEBP + - WIP + - WSL + - XML + - XSS + - YAML + - ZAP + - ZIP diff --git a/docs/.vale/gitlab/VersionText.yml b/docs/.vale/gitlab/VersionText.yml new file mode 100644 index 0000000000000000000000000000000000000000..571fba52ab7493d58cad6f1ea40a59794b49acce --- /dev/null +++ b/docs/.vale/gitlab/VersionText.yml @@ -0,0 +1,19 @@ +--- +# Error: gitlab.VersionText +# +# Checks that multi-line version text is formatted correctly. +# +# Specifically, looks for multi-line version text that doesn't use `-` to make it a list. +# For example: +# +# - `> Introduced in GitLab 14.0. +# - `> Removed in GitLab 15.0. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'This introduced-in section is not formatted correctly. Each entry must start with `> -` and long entries must be on one line.' +link: https://docs.gitlab.com/ee/development/documentation/versions.html +level: error +scope: raw +raw: + - '\n#.*\n\n> [^-].+\n[^\n`]' diff --git a/docs/.vale/gitlab/VersionTextSingleLine.yml b/docs/.vale/gitlab/VersionTextSingleLine.yml new file mode 100644 index 0000000000000000000000000000000000000000..f76574bcf8a397b43c919d2aa5f9506ddb066de5 --- /dev/null +++ b/docs/.vale/gitlab/VersionTextSingleLine.yml @@ -0,0 +1,13 @@ +--- +# Error: gitlab.VersionTextSingleLine +# +# Verifies that single-item version notes don't have a hyphen. +# +# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles +extends: existence +message: 'Version text with only a single item must not start with a hyphen.' +link: https://docs.gitlab.com/ee/development/documentation/versions.html#add-a-version-history-item +level: error +scope: raw +raw: + - '(\r|\n|\r\n){2}(> - .*)(\r|\n|\r\n){2}' diff --git a/docs/.vale/gitlab/Wordy.yml b/docs/.vale/gitlab/Wordy.yml new file mode 100644 index 0000000000000000000000000000000000000000..7888d16dadb17dd951c286cb5ab2118db2db423d --- /dev/null +++ b/docs/.vale/gitlab/Wordy.yml @@ -0,0 +1,17 @@ +--- +# Suggestion: gitlab.Wordy +# +# Suggests shorter versions of wordy phrases. +# +# For a list of all options, see https://docs.errata.ai/vale/styles +extends: substitution +message: '%s "%s".' +link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html +level: suggestion +ignorecase: true +swap: + in order to: "Be concise: use 'to' rather than" + needs? to: "Rewrite the sentence, or use 'must', instead of" + note that: "Be concise: rewrite the sentence to not use" + please: "Remove this word from the sentence: " + respectively: "Rewrite the sentence to be more precise, instead of using " diff --git a/docs/.vale/gitlab/spelling-exceptions.txt b/docs/.vale/gitlab/spelling-exceptions.txt new file mode 100644 index 0000000000000000000000000000000000000000..5d268fdb241d5578ae24e2c8cc34e06715311a10 --- /dev/null +++ b/docs/.vale/gitlab/spelling-exceptions.txt @@ -0,0 +1,879 @@ +accessor +accessors +Akismet +Alertmanager +Algolia +Alibaba +Aliyun +allowlist +allowlisted +allowlisting +allowlists +AlmaLinux +anonymization +anonymized +Ansible +Anthos +Apdex +Apparmor +approvers +architected +architecting +archiver +Arel +arity +Artifactory +Asana +Asciidoctor +asdf +Assembla +Atlassian +auditability +Auth0 +Authentiq +Authy +autocomplete +autocompleted +autocompletes +autocompleting +autogenerated +autoloaded +autoloader +autoloading +autoscale +autoscaled +autoscaler +autoscales +autoscaling +awardable +awardables +Axios +Ayoa +Azure +B-tree +backfilling +backport +backported +backporting +backports +backtrace +backtraced +backtraces +backtracing +badging +Bamboo +Bazel +Bhyve +Bitbucket +Bitnami +blockquote +blockquoted +blockquotes +blockquoting +boolean +booleans +Bootsnap +Bottlerocket +browsable +bugfix +bugfixed +bugfixes +bugfixing +Bugzilla +Buildkite +buildpack +buildpacks +bundler +bundlers +burndown +burnup +burstable +cacheable +Caddy +callstack +callstacks +Camo +canonicalization +canonicalized +captcha +Casdoor +CentOS +Ceph +Certbot +cgo +cgroup +cgroups +chai +changeset +changesets +ChaosKube +chatbot +chatbots +ChatOps +checksummed +checksumming +Chemlab +Citrix +Citus +clonable +Cloudwatch +Cobertura +Codeception +Codepen +Cognito +colocated +colocating +compilable +composable +composables +Conda +Consul +Contentful +Corosync +Coursier +cron +cronjob +cronjobs +crons +crontab +crontabs +crosslinked +crosslinking +crosslinks +Crossplane +Crowdin +CSV +customappsso +cybersecurity +Dangerfile +Datadog +datasource +datasources +datetime +Debian +Decompressor +decryptable +deduplicate +deduplicated +deduplicates +deduplicating +deduplication +deliverables +denormalize +denormalized +denormalizes +denormalizing +denylist +denylisted +denylisting +denylists +deployer +deployers +deprovision +deprovisioned +deprovisioning +deprovisions +dequarantine +dequarantined +dequarantining +deserialization +deserialize +deserializers +deserializes +DevOps +Dhall +disambiguates +discoverability +dismissable +Disqus +Distroless +Divio +Dockerfile +Dockerfiles +Dockerize +Dockerized +Dockerizing +dogfood +dogfooding +dogfoods +dotenv +downvoted +downvotes +Dpl +Dreamweaver +Ecto +ElastiCache +Elasticsearch +enablement +enqueued +enqueues +enum +enums +ETag +Excon +exfiltration +ExifTool +expirable +Facebook +failover +failovers +failsafe +Falco +falsy +Fargate +fastlane +Fastzip +favicon +favorited +Figma +Filebeat +Fio +firewalled +firewalling +fixup +Flawfinder +Flowdock +Fluentd +Flycheck +Forgerock +formatters +Fortinet +Fugit +fuzzer +Gantt +Gbps +Gemfile +Gemnasium +Gemojione +Getter +getters +Getters +gettext +Git +Gitaly +Gitea +GitHub +GitLab +gitlabsos +Gitleaks +Gitpod +Gitter +globals +Gmail +Godep +Gollum +Google +goroutine +goroutines +Gosec +Gradle +Grafana +Grafonnet +gravatar +Grype +Gzip +Hackathon +Haml +hardcode +hardcoded +hardcodes +Haswell +heatmap +heatmaps +Helm +Helmfile +Heroku +Herokuish +Hexo +HipChat +hostname +hostnames +hotfix +hotfixed +hotfixes +hotfixing +http +https +idempotence +idmapper +Iglu +Immer +inclusivity +Ingress +initializer +initializers +innersource +innersourcing +interdependencies +interdependency +interruptible +irker +issuables +Istio +Jaeger +jasmine-jquery +Javafuzz +JavaScript +Jenkins +Jenkinsfile +Jira +jq +jQuery +jsdom +Jsonnet +JupyterHub +Kaminari +kanban +kanbans +kaniko +Karma +Kerberos +Keycloak +keyset +keyspace +keytab +keytabs +Kibana +Kinesis +Klar +Knative +Kramdown +Kroki +Kubecost +kubectl +Kubernetes +Kubesec +Kustomize +Laravel +ldapsearch +Lefthook +Leiningen +libFuzzer +Libravatar +liveness +lockfiles +Lodash +Lograge +logrotate +Logrus +Logstash +lookahead +lookaheads +lookbehind +lookbehinds +lookups +loopback +Lucene +Maildir +Mailgun +Mailroom +Makefile +Makefiles +Markdown +markdownlint +Marketo +matcher +matchers +Matomo +Mattermost +mbox +memoization +memoize +memoized +memoizing +Memorystore +mergeability +mergeable +metaprogramming +Microsoft +middleware +middlewares +migratus +minikube +MinIO +misconfiguration +misconfigurations +misconfigure +misconfigured +misconfigures +misconfiguring +mitigations +mitmproxy +mixin +mixins +mockup +mockups +ModSecurity +Monokai +monorepo +monorepos +monospace +multiline +mutex +nameserver +nameservers +namespace +namespaced +namespaces +namespacing +namespacings +Nanoc +negatable +Netlify +Nokogiri +nosniff +noteable +noteables +npm +nullability +nullable +Nurtch +nyc +OAuth +Octokit +offboarded +offboarding +offboards +Okta +OmniAuth +onboarding +OpenID +OpenShift +Opsgenie +outdent +Overcommit +Packagist +parallelization +parallelizations +passwordless +Patroni +performant +PgBouncer +pgLoader +Phabricator +phaser +phasers +phpenv +pipenv +Pipfile +Pipfiles +Piwik +plaintext +Poedit +polyfill +polyfills +pooler +postfixed +postgres.ai +PostgreSQL +precompile +precompiled +preconfigure +preconfigured +preconfigures +prefill +prefilled +prefilling +prefills +preload +preloading +preloads +prepend +prepended +prepending +prepends +prepopulated +Prettifier +Pritaly +Priyanka +profiler +Prometheus +ProseMirror +protobuf +protobufs +proxied +proxies +proxyable +proxying +pseudocode +pseudonymization +pseudonymized +pseudonymizer +Puma +pytest +Python +Qualys +queryable +Quicktime +Rackspace +Raspbian +rbenv +rbtrace +Rclone +Rdoc +reachability +Realplayer +reauthenticate +reauthenticated +reauthenticates +reauthenticating +rebalancing +rebar +rebase +rebased +rebases +rebasing +reCAPTCHA +Redcarpet +redirection +redirections +Redis +Redmine +refactorings +referer +referers +reflog +reflogs +refspec +refspecs +reindex +reindexed +reindexes +reindexing +reinitialize +reinitializing +relicensing +remediations +renderers +replicables +repmgr +repmgrd +repurposing +requeue +requeued +requeues +requeuing +Restlet +resync +resynced +resyncing +resyncs +retarget +retargeted +retargeting +retargets +reusability +reverified +reverifies +reverify +roadmap +roadmaps +rollout +rollouts +rsync +rsynced +rsyncing +rsyncs +Rubinius +Rubix +RuboCop +Rubular +ruleset +rulesets +runbook +runbooks +runit +runtime +runtimes +Salesforce +sandboxing +sanitization +sbt +scalers +scatterplot +scatterplots +Schemastore +scrollable +Semgrep +Sendmail +Sentry +serializer +serializers +serializing +serverless +setuptools +severities +sharded +sharding +shfmt +Shimo +Shopify +Sidekiq +Silverlight +Sisense +Sitespeed +skippable +Slack +Slackbot +Slony +smartcard +smartcards +snapshotting +Snyk +Sobelow +Solargraph +Solarized +Sourcegraph +Spamcheck +spammable +sparkline +sparklines +spidering +Splunk +SpotBugs +Stackdriver +Stackprof +starrer +starrers +storable +storages +strace +strikethrough +strikethroughs +stunnel +stylelint +subchart +subcharts +subcommand +subcommands +subfolder +subfolders +subgraph +subgraphs +subgroup +subgroups +subkey +subkeys +sublicense +sublicensed +sublicenses +sublicensing +subnet +subnets +subnetting +subpath +subproject +subprojects +subqueried +subqueries +subquery +subquerying +substring +substrings +subtask +subtasks +subtest +subtests +subtree +subtrees +sudo +supercookie +supercookies +superset +supersets +supertype +supertypes +swappiness +swimlane +swimlanes +syncable +Sysbench +syscall +syscalls +syslog +systemd +tanuki +tcpdump +templated +Thanos +Thoughtbot +throughputs +Tiller +timebox +timeboxed +timeboxes +timeboxing +timecop +tiptap +todos +tokenizer +Tokenizers +tokenizing +tolerations +toolchain +toolchains +toolkit +toolkits +tooltip +tooltips +transactionally +transpile +transpiled +transpiles +transpiling +Trello +triaged +triages +triaging +Trivy +Truststore +truthy +Twilio +Twitter +TypeScript +Ubuntu +Udemy +unapplied +unapprove +unapproved +unapproving +unarchive +unarchived +unarchives +unarchiving +unary +unassign +unassigning +unassigns +unban +uncheck +unchecked +unchecking +unchecks +uncomment +uncommented +uncommenting +uncordon +unencode +unencoded +unencoder +unencodes +unencrypted +unfollow +unfollowed +unfollows +Unicorn +unindexed +unlink +unlinking +unlinks +unmappable +unmapped +unmergeable +unmerged +unmerges +unmerging +unmocked +unoptimize +unoptimized +unoptimizes +unoptimizing +unpatched +unprioritized +unprotect +unprotected +unprotecting +unprotects +unprovision +unprovisioned +unprovisions +unpublish +unpublished +unpublishes +unpublishing +unpushed +unreferenced +unregister +unregistered +unregisters +unreplicated +unresolve +unresolved +unresolving +unreviewed +unsanitized +unschedule +unscoped +unshare +unshared +unshares +unstage +unstaged +unstages +unstaging +unstar +unstars +unstarted +unstash +unstashed +unstashing +unsynced +unsynchronized +untarred +untracked +untrusted +unverified +unverifies +unverify +unverifying +uploader +uploaders +upstreams +upvote +upvoted +upvotes +URIs +Vagrantfile +validator +validators +vendored +vendoring +versionless +viewport +viewports +virtualized +virtualizing +Vue +Vuex +walkthrough +walkthroughs +WebdriverIO +Webex +webpack +webserver +Webservice +websocket +websockets +whitepaper +whitepapers +wireframe +wireframed +wireframes +wireframing +Wireshark +Wordpress +Workato +worktree +worktrees +Worldline +Xcode +Xeon +YouTrack +ytt +Yubico +Zabbix +Zeitwerk +Zendesk +ZenTao +zsh +Zstandard diff --git a/docs/.vale/vale-json.tmpl b/docs/.vale/vale-json.tmpl new file mode 100644 index 0000000000000000000000000000000000000000..ed3c3259df32421aa54bb261f5a442c388174324 --- /dev/null +++ b/docs/.vale/vale-json.tmpl @@ -0,0 +1,58 @@ +{{- /* Modify Vale's output https://docs.errata.ai/vale/cli#--output */ -}} + +{{- /* Keep track of our various counts */ -}} + +{{- $e := 0 -}} +{{- $w := 0 -}} +{{- $s := 0 -}} +{{- $f := 0 -}} + +{{- /* Range over the linted files */ -}} + +{{- range .Files}} + +{{- $f = add1 $f -}} +{{- $path := .Path -}} + +{{- /* Range over the file's alerts */ -}} +[ + +{{- range $idx, $a := .Alerts -}} + +{{- $error := "" -}} +{{- if eq .Severity "error" -}} + {{- $error = .Severity -}} + {{- $e = add1 $e -}} +{{- else if eq .Severity "warning" -}} + {{- $error = .Severity -}} + {{- $w = add1 $w -}} +{{- else -}} + {{- $error = .Severity -}} + {{- $s = add1 $s -}} +{{- end}} + +{{- /* Variables setup */ -}} + +{{- $path = $path -}} +{{- $loc := printf "%d" .Line -}} +{{- $check := printf "%s" .Check -}} +{{- $message := printf "%s" .Message -}} +{{- $link := printf "%s" .Link -}} +{{- if $idx -}},{{- end -}} + +{{- /* Output */ -}} + + { + "description": "{{ $message }}", + "fingerprint": "{{ $path }}-{{ $loc }}", + "severity": "{{ $error }}", + "location": { + "path": "{{ $path }}", + "lines": { + "begin": {{ $loc }} + } + } + } +{{end -}} +{{end -}} +] diff --git a/docs/.vale/vale.tmpl b/docs/.vale/vale.tmpl new file mode 100644 index 0000000000000000000000000000000000000000..8a6c6e5157dc43b0acf84abb8fac8d37af7322fc --- /dev/null +++ b/docs/.vale/vale.tmpl @@ -0,0 +1,51 @@ +{{- /* Modify Vale's output https://docs.errata.ai/vale/cli#--output */ -}} + +{{- /* Keep track of our various counts */ -}} + +{{- $e := 0 -}} +{{- $w := 0 -}} +{{- $s := 0 -}} +{{- $f := 0 -}} + +{{- /* Range over the linted files */ -}} + +{{- range .Files}} + +{{- $f = add1 $f -}} +{{- $path := .Path | underline -}} + +{{- /* Range over the file's alerts */ -}} + +{{- range .Alerts -}} + +{{- $error := "" -}} +{{- if eq .Severity "error" -}} + {{- $error = .Severity | red -}} + {{- $e = add1 $e -}} +{{- else if eq .Severity "warning" -}} + {{- $error = .Severity | yellow -}} + {{- $w = add1 $w -}} +{{- else -}} + {{- $error = .Severity | blue -}} + {{- $s = add1 $s -}} +{{- end}} + +{{- /* Variables setup */ -}} + +{{- $path = $path -}} +{{- $loc := printf "Line %d, position %d" .Line (index .Span 0) -}} +{{- $check := printf "%s" .Check -}} +{{- $message := printf "%s" .Message -}} +{{- $link := printf "%s" .Link -}} + +{{- /* Output */ -}} + +{{ $path }}: + {{ $loc }} (rule {{ $check }}) + {{ $error }}: {{ $message }} + More information: {{ $link }} + +{{end -}} +{{end -}} + +{{- $e}} {{"errors" | red}}, {{$w}} {{"warnings" | yellow}}, and {{$s}} {{"suggestions" | blue}} found. diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf1020d5c292abdedf27627c6abe25e2293..0000000000000000000000000000000000000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 6247f7e231716482115f34084ac61030743e0715..0000000000000000000000000000000000000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/source/_static/glab.png b/docs/source/_static/glab.png deleted file mode 100644 index b350d4d9593d5f9e385c88fb65b9c432301d5dde..0000000000000000000000000000000000000000 Binary files a/docs/source/_static/glab.png and /dev/null differ diff --git a/docs/source/alias/delete.md b/docs/source/alias/delete.md new file mode 100644 index 0000000000000000000000000000000000000000..f0ae3fb0933327f874a55d3080ec5fbb157620b6 --- /dev/null +++ b/docs/source/alias/delete.md @@ -0,0 +1,14 @@ +## glab alias delete + +Delete an alias. + +``` +glab alias delete [flags] +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + diff --git a/docs/source/alias/delete.rst b/docs/source/alias/delete.rst deleted file mode 100644 index eb4b03d60e399d9a889162edf3e9d32c832d759f..0000000000000000000000000000000000000000 --- a/docs/source/alias/delete.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _glab_alias_delete: - -glab alias delete ------------------ - -Delete an alias. - -Synopsis -~~~~~~~~ - - -Delete an alias. - -:: - - glab alias delete [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - diff --git a/docs/source/alias/help.md b/docs/source/alias/help.md new file mode 100644 index 0000000000000000000000000000000000000000..e05f3d3daf3ecf3d1ea603ee417844ed853fb4c2 --- /dev/null +++ b/docs/source/alias/help.md @@ -0,0 +1,19 @@ +## glab alias help + +Help about any command + +### Synopsis + +Help provides help for any command in the application. +Simply type alias help [path to command] for full details. + +``` +glab alias help [command] [flags] +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + diff --git a/docs/source/alias/help.rst b/docs/source/alias/help.rst deleted file mode 100644 index e3d17bb0cb4a51f4b8b6995b3c56a6de3a3fd181..0000000000000000000000000000000000000000 --- a/docs/source/alias/help.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _glab_alias_help: - -glab alias help ---------------- - -Help about any command - -Synopsis -~~~~~~~~ - - -Help provides help for any command in the application. -Simply type alias help [path to command] for full details. - -:: - - glab alias help [command] [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - diff --git a/docs/source/alias/index.md b/docs/source/alias/index.md new file mode 100755 index 0000000000000000000000000000000000000000..dce762c84c1b369b248c958bf3d57a5269ac8701 --- /dev/null +++ b/docs/source/alias/index.md @@ -0,0 +1,16 @@ +## glab alias + +Create, list and delete aliases + +### Options inherited from parent commands + +``` + --help Show help for command +``` + +### Subcommands + +- [delete](delete.md) +- [list](list.md) +- [set](set.md) + diff --git a/docs/source/alias/index.rst b/docs/source/alias/index.rst deleted file mode 100755 index b4bf665c8e64d58c3d2c6ed61b7ae79bc100a5c2..0000000000000000000000000000000000000000 --- a/docs/source/alias/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _glab_alias: - -glab alias ----------- - -Create, list and delete aliases - -Synopsis -~~~~~~~~ - - -Create, list and delete aliases - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -Subcommands -~~~~~~~~~~~ -.. toctree:: - :glob: - :maxdepth: 0 - - delete - list - set - - - diff --git a/docs/source/alias/list.md b/docs/source/alias/list.md new file mode 100644 index 0000000000000000000000000000000000000000..12dba6dbb479eb2cadcc701829aa1d522d5207f5 --- /dev/null +++ b/docs/source/alias/list.md @@ -0,0 +1,14 @@ +## glab alias list + +List the available aliases. + +``` +glab alias list [flags] +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + diff --git a/docs/source/alias/list.rst b/docs/source/alias/list.rst deleted file mode 100644 index 06145639a59d99a248eb6333e09428eb785d192b..0000000000000000000000000000000000000000 --- a/docs/source/alias/list.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _glab_alias_list: - -glab alias list ---------------- - -List the available aliases. - -Synopsis -~~~~~~~~ - - -List the available aliases. - -:: - - glab alias list [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - diff --git a/docs/source/alias/set.rst b/docs/source/alias/set.md similarity index 60% rename from docs/source/alias/set.rst rename to docs/source/alias/set.md index 46e54888a201c588231209ffae9110e384664e08..b29d91e141ad24e3edb1e90037dc7f337ea46916 100644 --- a/docs/source/alias/set.rst +++ b/docs/source/alias/set.md @@ -1,13 +1,8 @@ -.. _glab_alias_set: - -glab alias set --------------- +## glab alias set Set an alias. -Synopsis -~~~~~~~~ - +### Synopsis Declare a word as a command alias that will expand to the specified command(s). @@ -25,39 +20,36 @@ you have installed git on Windows in some other way, shell aliases may not work Quotes must always be used when defining a command as in the examples. -:: +``` +glab alias set '' [flags] +``` - glab alias set '' [flags] +### Examples -Examples -~~~~~~~~ +``` +$ glab alias set mrv 'mr view' +$ glab mrv -w 123 +#=> glab mr view -w 123 -:: +$ glab alias set createissue 'glab create issue --title "$1"' +$ glab createissue "My Issue" --description "Something is broken." +# => glab create issue --title "My Issue" --description "Something is broken." - $ glab alias set mrv 'mr view' - $ glab mrv -w 123 - #=> glab mr view -w 123 - - $ glab alias set createissue 'glab create issue --title "$1"' - $ glab createissue "My Issue" --description "Something is broken." - # => glab create issue --title "My Issue" --description "Something is broken." - - $ glab alias set --shell igrep 'glab issue list --assignee="$1" | grep $2' - $ glab igrep user foo - #=> glab issue list --assignee="user" | grep "foo" - +$ glab alias set --shell igrep 'glab issue list --assignee="$1" | grep $2' +$ glab igrep user foo +#=> glab issue list --assignee="user" | grep "foo" -Options -~~~~~~~ +``` -:: +### Options +``` -s, --shell Declare an alias to be passed through a shell interpreter +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command +``` diff --git a/docs/source/api/index.rst b/docs/source/api/index.md similarity index 75% rename from docs/source/api/index.rst rename to docs/source/api/index.md index 40617a0d154892ed811d37279e531b9da84a82af..1acf0df97870230ad3a9db86022a5512a8314a82 100755 --- a/docs/source/api/index.rst +++ b/docs/source/api/index.md @@ -1,13 +1,8 @@ -.. _glab_api: - -glab api --------- +## glab api Make an authenticated request to GitLab API -Synopsis -~~~~~~~~ - +### Synopsis Makes an authenticated HTTP request to the GitLab API and prints the response. The endpoint argument should either be a path of a GitLab API v4 endpoint, or @@ -51,64 +46,61 @@ there are no more pages of results. For GraphQL requests, this requires that the original query accepts an '$endCursor: String' variable and that it fetches the 'pageInfo{ hasNextPage, endCursor }' set of fields from a collection. -:: +``` +glab api [flags] +``` - glab api [flags] +### Examples -Examples -~~~~~~~~ +``` +$ glab api projects/:fullpath/releases -:: +$ glab api projects/gitlab-com%2Fwww-gitlab-com/issues - $ glab api projects/:fullpath/releases - - $ glab api projects/gitlab-com%2Fwww-gitlab-com/issues - - $ glab api issues --paginate - - $ glab api graphql -f query=' - query { - project(fullPath: "gitlab-org/gitlab-docs") { - name - forksCount - statistics { - wikiSize - } - issuesEnabled - boards { - nodes { - id - name - } +$ glab api issues --paginate + +$ glab api graphql -f query=' + query { + project(fullPath: "gitlab-org/gitlab-docs") { + name + forksCount + statistics { + wikiSize + } + issuesEnabled + boards { + nodes { + id + name } } } - ' - - $ glab api graphql --paginate -f query=' - query($endCursor: String) { - project(fullPath: "gitlab-org/graphql-sandbox") { - name - issues(first: 2, after: $endCursor) { - edges { - node { - title - } - } - pageInfo { - endCursor - hasNextPage + } +' + +$ glab api graphql --paginate -f query=' + query($endCursor: String) { + project(fullPath: "gitlab-org/graphql-sandbox") { + name + issues(first: 2, after: $endCursor) { + edges { + node { + title } } + pageInfo { + endCursor + hasNextPage + } } - }' - + } + }' -Options -~~~~~~~ +``` -:: +### Options +``` -F, --field stringArray Add a parameter of inferred type -H, --header stringArray Add an additional HTTP request header --hostname string The GitLab hostname for the request (default is "gitlab.com" or authenticated host in current git directory) @@ -118,11 +110,11 @@ Options --paginate Make additional HTTP requests to fetch all pages of results -f, --raw-field stringArray Add a string parameter --silent Do not print the response body +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command +``` diff --git a/docs/source/auth/git-credential.md b/docs/source/auth/git-credential.md new file mode 100644 index 0000000000000000000000000000000000000000..fa6abdb0d9dee2e9847a969804e1a47548f3bb8c --- /dev/null +++ b/docs/source/auth/git-credential.md @@ -0,0 +1,14 @@ +## glab auth git-credential + +Implements git credential helper manager + +``` +glab auth git-credential [flags] +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + diff --git a/docs/source/auth/git-credential.rst b/docs/source/auth/git-credential.rst deleted file mode 100644 index 0dad2f72fea77de3baa3d9d8b44d67917d1bbc7e..0000000000000000000000000000000000000000 --- a/docs/source/auth/git-credential.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _glab_auth_git-credential: - -glab auth git-credential ------------------------- - -Implements git credential helper manager - -Synopsis -~~~~~~~~ - - -Implements git credential helper manager - -:: - - glab auth git-credential [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - diff --git a/docs/source/auth/help.md b/docs/source/auth/help.md new file mode 100644 index 0000000000000000000000000000000000000000..5db62b6fa41d5f711cd7c0a4ec392e11ce737362 --- /dev/null +++ b/docs/source/auth/help.md @@ -0,0 +1,19 @@ +## glab auth help + +Help about any command + +### Synopsis + +Help provides help for any command in the application. +Simply type auth help [path to command] for full details. + +``` +glab auth help [command] [flags] +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + diff --git a/docs/source/auth/help.rst b/docs/source/auth/help.rst deleted file mode 100644 index 949b779085966ee5da96151eca761fa5122b402c..0000000000000000000000000000000000000000 --- a/docs/source/auth/help.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _glab_auth_help: - -glab auth help --------------- - -Help about any command - -Synopsis -~~~~~~~~ - - -Help provides help for any command in the application. -Simply type auth help [path to command] for full details. - -:: - - glab auth help [command] [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - diff --git a/docs/source/auth/index.md b/docs/source/auth/index.md new file mode 100755 index 0000000000000000000000000000000000000000..24b646553bd3aed7ee1b03dfdf02ac50f766033c --- /dev/null +++ b/docs/source/auth/index.md @@ -0,0 +1,16 @@ +## glab auth + +Manage glab's authentication state + +### Options inherited from parent commands + +``` + --help Show help for command +``` + +### Subcommands + +- [git-credential](git-credential.md) +- [login](login.md) +- [status](status.md) + diff --git a/docs/source/auth/index.rst b/docs/source/auth/index.rst deleted file mode 100755 index 3677d8a634523930208384a8d60e9e3343aadc90..0000000000000000000000000000000000000000 --- a/docs/source/auth/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -.. _glab_auth: - -glab auth ---------- - -Manage glab's authentication state - -Synopsis -~~~~~~~~ - - -Manage glab's authentication state - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -Subcommands -~~~~~~~~~~~ -.. toctree:: - :glob: - :maxdepth: 0 - - git-credential - login - status - - - diff --git a/docs/source/auth/login.md b/docs/source/auth/login.md new file mode 100644 index 0000000000000000000000000000000000000000..2ece19e0367c7364db3288f8f65ac457d74009d0 --- /dev/null +++ b/docs/source/auth/login.md @@ -0,0 +1,41 @@ +## glab auth login + +Authenticate with a GitLab instance + +### Synopsis + +Authenticate with a GitLab instance. +You can pass in a token on standard input by using `--stdin`. +The minimum required scopes for the token are: "api", "write_repository". + + +``` +glab auth login [flags] +``` + +### Examples + +``` +# start interactive setup +$ glab auth login +# authenticate against gitlab.com by reading the token from a file +$ glab auth login --stdin < myaccesstoken.txt +# authenticate with a self-hosted GitLab instance +$ glab auth login --hostname salsa.debian.org + +``` + +### Options + +``` + -h, --hostname string The hostname of the GitLab instance to authenticate with + --stdin Read token from standard input + -t, --token string Your GitLab access token +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + diff --git a/docs/source/auth/login.rst b/docs/source/auth/login.rst deleted file mode 100644 index c0afa7f10a04aae0a1663646417b685051e72f55..0000000000000000000000000000000000000000 --- a/docs/source/auth/login.rst +++ /dev/null @@ -1,49 +0,0 @@ -.. _glab_auth_login: - -glab auth login ---------------- - -Authenticate with a GitLab instance - -Synopsis -~~~~~~~~ - - -Authenticate with a GitLab instance. -You can pass in a token on standard input by using `--stdin`. -The minimum required scopes for the token are: "api", "write_repository". - - -:: - - glab auth login [flags] - -Examples -~~~~~~~~ - -:: - - # start interactive setup - $ glab auth login - # authenticate against gitlab.com by reading the token from a file - $ glab auth login --stdin < myaccesstoken.txt - # authenticate with a self-hosted GitLab instance - $ glab auth login --hostname salsa.debian.org - - -Options -~~~~~~~ - -:: - - -h, --hostname string The hostname of the GitLab instance to authenticate with - --stdin Read token from standard input - -t, --token string Your GitLab access token - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - diff --git a/docs/source/auth/status.rst b/docs/source/auth/status.md similarity index 64% rename from docs/source/auth/status.rst rename to docs/source/auth/status.md index 325ac2fb7d8a31401809eed82d31eac9c6b416ce..8f7ba270d1ea49cd3f35ddd32d762bb7c3cfd1b2 100644 --- a/docs/source/auth/status.rst +++ b/docs/source/auth/status.md @@ -1,35 +1,28 @@ -.. _glab_auth_status: - -glab auth status ----------------- +## glab auth status View authentication status -Synopsis -~~~~~~~~ - +### Synopsis Verifies and displays information about your authentication state. This command tests the authentication states of all known GitLab instances in the config file and reports issues if any -:: - - glab auth status [flags] +``` +glab auth status [flags] +``` -Options -~~~~~~~ - -:: +### Options +``` -h, --hostname string Check a specific instance's authentication status -t, --show-token Display the auth token +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command +``` diff --git a/docs/source/check-update/index.md b/docs/source/check-update/index.md new file mode 100755 index 0000000000000000000000000000000000000000..b0cd013cf7218bcffeb2d3f570b803cf7042dde1 --- /dev/null +++ b/docs/source/check-update/index.md @@ -0,0 +1,14 @@ +## glab check-update + +Check for latest glab releases + +``` +glab check-update [flags] +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + diff --git a/docs/source/check-update/index.rst b/docs/source/check-update/index.rst deleted file mode 100755 index 5a280860731c81ea8e64522e9e5da49d570ca2a8..0000000000000000000000000000000000000000 --- a/docs/source/check-update/index.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _glab_check-update: - -glab check-update ------------------ - -Check for latest glab releases - -Synopsis -~~~~~~~~ - - -Check for latest glab releases - -:: - - glab check-update [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - diff --git a/docs/source/ci/artifact.md b/docs/source/ci/artifact.md new file mode 100644 index 0000000000000000000000000000000000000000..082c7389e4ada586455b81586680b354e5b83814 --- /dev/null +++ b/docs/source/ci/artifact.md @@ -0,0 +1,29 @@ +## glab ci artifact + +Download all Artifacts from the last pipeline + +``` +glab ci artifact [flags] +``` + +### Examples + +``` +$ glab ci artifact main build +$ glab ci artifact main deploy --path="artifacts/" + +``` + +### Options + +``` + -p, --path string Path to download the Artifact files (default ./) +``` + +### Options inherited from parent commands + +``` + --help Show help for command + -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` + diff --git a/docs/source/ci/ci.md b/docs/source/ci/ci.md new file mode 100644 index 0000000000000000000000000000000000000000..a89f41c5b40e5dcf24829451c8f5b450d824218b --- /dev/null +++ b/docs/source/ci/ci.md @@ -0,0 +1,24 @@ +## glab ci ci + +Work with GitLab CI pipelines and jobs + +### Examples + +``` +$ glab pipeline ci trace + +``` + +### Options inherited from parent commands + +``` + --help Show help for command + -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` + +### Subcommands + +- [lint](lint.md) +- [trace](trace.md) +- [view](view.md) + diff --git a/docs/source/ci/ci.rst b/docs/source/ci/ci.rst deleted file mode 100644 index 4b5da02e1a33b532c9638f2af56530f716db2afb..0000000000000000000000000000000000000000 --- a/docs/source/ci/ci.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. _glab_ci_ci: - -glab ci ci ----------- - -Work with GitLab CI pipelines and jobs - -Synopsis -~~~~~~~~ - - -Work with GitLab CI pipelines and jobs - -Examples -~~~~~~~~ - -:: - - $ glab pipeline ci trace - - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL - -Subcommands -~~~~~~~~~~~ -.. toctree:: - :glob: - :maxdepth: 0 - - lint - trace - view - - - diff --git a/docs/source/ci/delete.rst b/docs/source/ci/delete.md similarity index 51% rename from docs/source/ci/delete.rst rename to docs/source/ci/delete.md index 84c265860a17d1e4bc1bb24177483c76253ad121..60298c2c8b1c57661300329a187405a85f7522cc 100644 --- a/docs/source/ci/delete.rst +++ b/docs/source/ci/delete.md @@ -1,41 +1,29 @@ -.. _glab_ci_delete: - -glab ci delete --------------- - -Delete a CI pipeline - -Synopsis -~~~~~~~~ - +## glab ci delete Delete a CI pipeline -:: - - glab ci delete [flags] +``` +glab ci delete [flags] +``` -Examples -~~~~~~~~ +### Examples -:: +``` +$ glab ci delete 34 +$ glab ci delete 12,34,2 - $ glab ci delete 34 - $ glab ci delete 12,34,2 - +``` -Options -~~~~~~~ - -:: +### Options +``` -s, --status string delete pipelines by status: {running|pending|success|failed|canceled|skipped|created|manual} +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` diff --git a/docs/source/ci/help.rst b/docs/source/ci/help.md similarity index 63% rename from docs/source/ci/help.rst rename to docs/source/ci/help.md index 1f859f16b5a48de4403ca74742a96e0310143754..7ef56f1c9814320a53b852a97509f4ac3fddb2d1 100644 --- a/docs/source/ci/help.rst +++ b/docs/source/ci/help.md @@ -1,26 +1,20 @@ -.. _glab_ci_help: - -glab ci help ------------- +## glab ci help Help about any command -Synopsis -~~~~~~~~ - +### Synopsis Help provides help for any command in the application. Simply type ci help [path to command] for full details. -:: - - glab ci help [command] [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` +glab ci help [command] [flags] +``` -:: +### Options inherited from parent commands +``` --help Show help for command -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` diff --git a/docs/source/ci/index.md b/docs/source/ci/index.md new file mode 100755 index 0000000000000000000000000000000000000000..f1399c46c8ae7f9d50fa06df175b029f7ee6ad02 --- /dev/null +++ b/docs/source/ci/index.md @@ -0,0 +1,29 @@ +## glab ci + +Work with GitLab CI pipelines and jobs + +### Options + +``` + -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + +### Subcommands + +- [artifact](artifact.md) +- [ci](ci.md) +- [delete](delete.md) +- [lint](lint.md) +- [list](list.md) +- [retry](retry.md) +- [run](run.md) +- [status](status.md) +- [trace](trace.md) +- [view](view.md) + diff --git a/docs/source/ci/index.rst b/docs/source/ci/index.rst deleted file mode 100755 index 588019f67bdbfb04904e8e92899fc3807380c44e..0000000000000000000000000000000000000000 --- a/docs/source/ci/index.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _glab_ci: - -glab ci -------- - -Work with GitLab CI pipelines and jobs - -Synopsis -~~~~~~~~ - - -Work with GitLab CI pipelines and jobs - -Options -~~~~~~~ - -:: - - -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -Subcommands -~~~~~~~~~~~ -.. toctree:: - :glob: - :maxdepth: 0 - - ci - delete - lint - list - retry - run - status - trace - view - - - diff --git a/docs/source/ci/lint.md b/docs/source/ci/lint.md new file mode 100644 index 0000000000000000000000000000000000000000..c34a26e7ce62dff98d328d3b69892a799ca67202 --- /dev/null +++ b/docs/source/ci/lint.md @@ -0,0 +1,27 @@ +## glab ci lint + +Checks if your .gitlab-ci.yml file is valid. + +``` +glab ci lint [flags] +``` + +### Examples + +``` +$ glab ci lint +#=> Uses .gitlab-ci.yml in the current directory + +$ glab ci lint .gitlab-ci.yml + +$ glab ci lint path/to/.gitlab-ci.yml + +``` + +### Options inherited from parent commands + +``` + --help Show help for command + -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` + diff --git a/docs/source/ci/lint.rst b/docs/source/ci/lint.rst deleted file mode 100644 index e89f8c41b1346ff9bdcd8aac072137c72641bf33..0000000000000000000000000000000000000000 --- a/docs/source/ci/lint.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. _glab_ci_lint: - -glab ci lint ------------- - -Checks if your .gitlab-ci.yml file is valid. - -Synopsis -~~~~~~~~ - - -Checks if your .gitlab-ci.yml file is valid. - -:: - - glab ci lint [flags] - -Examples -~~~~~~~~ - -:: - - $ glab ci lint - #=> Uses .gitlab-ci.yml in the current directory - - $ glab ci lint .gitlab-ci.yml - - $ glab ci lint path/to/.gitlab-ci.yml - - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL - diff --git a/docs/source/ci/list.rst b/docs/source/ci/list.md similarity index 67% rename from docs/source/ci/list.rst rename to docs/source/ci/list.md index 643ac44a3e1368e1c725b887316b66be9e539414..3b0bc0d89988b1de06d659a3e53ecf766e06d61b 100644 --- a/docs/source/ci/list.rst +++ b/docs/source/ci/list.md @@ -1,45 +1,33 @@ -.. _glab_ci_list: - -glab ci list ------------- - -Get the list of CI pipelines - -Synopsis -~~~~~~~~ - +## glab ci list Get the list of CI pipelines -:: - - glab ci list [flags] +``` +glab ci list [flags] +``` -Examples -~~~~~~~~ +### Examples -:: +``` +$ glab ci list +$ glab ci list --status=failed - $ glab ci list - $ glab ci list --state=failed - +``` -Options -~~~~~~~ - -:: +### Options +``` -o, --orderBy string Order pipeline by -p, --page int Page number (default 1) -P, --per-page int Number of items to list per page. (default 30) (default 30) --sort string Sort pipeline by {asc|desc}. (Defaults to desc) (default "desc") -s, --status string Get pipeline with status: {running|pending|success|failed|canceled|skipped|created|manual} +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` diff --git a/docs/source/ci/retry.md b/docs/source/ci/retry.md new file mode 100644 index 0000000000000000000000000000000000000000..eeab57e189407dc0411d63f556d29c55fa5c24b7 --- /dev/null +++ b/docs/source/ci/retry.md @@ -0,0 +1,22 @@ +## glab ci retry + +Retry a CI job + +``` +glab ci retry [flags] +``` + +### Examples + +``` +$ glab ci retry 871528 + +``` + +### Options inherited from parent commands + +``` + --help Show help for command + -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` + diff --git a/docs/source/ci/retry.rst b/docs/source/ci/retry.rst deleted file mode 100644 index 2be3c2f1f20afb47c2980603a68bd6633e67ca76..0000000000000000000000000000000000000000 --- a/docs/source/ci/retry.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _glab_ci_retry: - -glab ci retry -------------- - -Retry a CI job - -Synopsis -~~~~~~~~ - - -Retry a CI job - -:: - - glab ci retry [flags] - -Examples -~~~~~~~~ - -:: - - $ glab ci retry 871528 - - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL - diff --git a/docs/source/ci/run.md b/docs/source/ci/run.md new file mode 100644 index 0000000000000000000000000000000000000000..8fb8730e12b7e0761dd0720377c7f6035222c0a9 --- /dev/null +++ b/docs/source/ci/run.md @@ -0,0 +1,32 @@ +## glab ci run + +Create or run a new CI pipeline + +``` +glab ci run [flags] +``` + +### Examples + +``` +$ glab ci run +$ glab ci run -b main +$ glab ci run -b main --variables MYKEY:some_value + $ glab ci run -b main --variables MYKEY:some_value --variables KEY2:another_value + +``` + +### Options + +``` + -b, --branch string Create pipeline on branch/ref + --variables strings Pass variables to pipeline +``` + +### Options inherited from parent commands + +``` + --help Show help for command + -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` + diff --git a/docs/source/ci/run.rst b/docs/source/ci/run.rst deleted file mode 100644 index 07288fcb95be9cd196d1b5c48a893c6b55b00424..0000000000000000000000000000000000000000 --- a/docs/source/ci/run.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _glab_ci_run: - -glab ci run ------------ - -Create or run a new CI pipeline - -Synopsis -~~~~~~~~ - - -Create or run a new CI pipeline - -:: - - glab ci run [flags] - -Examples -~~~~~~~~ - -:: - - $ glab ci run - $ glab ci run -b main - $ glab ci run -b main --variables MYKEY:some_value - $ glab ci run -b main --variables MYKEY:some_value --variables KEY2:another_value - - -Options -~~~~~~~ - -:: - - -b, --branch string Create pipeline on branch/ref - --variables strings Pass variables to pipeline - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL - diff --git a/docs/source/ci/status.md b/docs/source/ci/status.md new file mode 100644 index 0000000000000000000000000000000000000000..4d65a1c2b2bec808200671be46fea233de7a0e78 --- /dev/null +++ b/docs/source/ci/status.md @@ -0,0 +1,33 @@ +## glab ci status + +View a running CI pipeline on current or other branch specified + +``` +glab ci status [flags] +``` + +### Examples + +``` +$ glab ci status --live +$ glab ci status --compact // more compact view +$ glab ci status --branch=master // Get pipeline for master branch +$ glab ci status // Get pipeline for current branch + +``` + +### Options + +``` + -b, --branch string Check pipeline status for a branch. (Default is current branch) + -c, --compact Show status in compact format + -l, --live Show status in real-time till pipeline ends +``` + +### Options inherited from parent commands + +``` + --help Show help for command + -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` + diff --git a/docs/source/ci/status.rst b/docs/source/ci/status.rst deleted file mode 100644 index a0640f6d79d6e37f3558bd1078eabad75975f515..0000000000000000000000000000000000000000 --- a/docs/source/ci/status.rst +++ /dev/null @@ -1,45 +0,0 @@ -.. _glab_ci_status: - -glab ci status --------------- - -View a running CI pipeline on current or other branch specified - -Synopsis -~~~~~~~~ - - -View a running CI pipeline on current or other branch specified - -:: - - glab ci status [flags] - -Examples -~~~~~~~~ - -:: - - $ glab ci status --live - $ glab ci status --compact // more compact view - $ glab ci status --branch=master // Get pipeline for master branch - $ glab ci status // Get pipeline for current branch - - -Options -~~~~~~~ - -:: - - -b, --branch string Check pipeline status for a branch. (Default is current branch) - -c, --compact Show status in compact format - -l, --live Show status in real-time till pipeline ends - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL - diff --git a/docs/source/ci/trace.md b/docs/source/ci/trace.md new file mode 100644 index 0000000000000000000000000000000000000000..ffb88e9032326788c050d11cb42b032ad10299d5 --- /dev/null +++ b/docs/source/ci/trace.md @@ -0,0 +1,32 @@ +## glab ci trace + +Trace a CI job log in real time + +``` +glab ci trace [] [flags] +``` + +### Examples + +``` +$ glab ci trace +#=> interactively select a job to trace + +$ glab ci trace 224356863 +#=> trace job with id 224356863 + +``` + +### Options + +``` + -b, --branch string Check pipeline status for a branch. (Default is the current branch) +``` + +### Options inherited from parent commands + +``` + --help Show help for command + -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` + diff --git a/docs/source/ci/trace.rst b/docs/source/ci/trace.rst deleted file mode 100644 index df5e0113cd77fd48f2dfbdaf79a8052dae4bcbcd..0000000000000000000000000000000000000000 --- a/docs/source/ci/trace.rst +++ /dev/null @@ -1,44 +0,0 @@ -.. _glab_ci_trace: - -glab ci trace -------------- - -Trace a CI job log in real time - -Synopsis -~~~~~~~~ - - -Trace a CI job log in real time - -:: - - glab ci trace [] [flags] - -Examples -~~~~~~~~ - -:: - - $ glab ci trace - #=> interactively select a job to trace - - $ glab ci trace 224356863 - #=> trace job with id 224356863 - - -Options -~~~~~~~ - -:: - - -b, --branch string Check pipeline status for a branch. (Default is the current branch) - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL - diff --git a/docs/source/ci/view.rst b/docs/source/ci/view.md similarity index 61% rename from docs/source/ci/view.rst rename to docs/source/ci/view.md index 77f80263db42c1674e9dcfd2b68c537198c24c40..093ea51a96c07cfb23f300f256478ea800c32a66 100644 --- a/docs/source/ci/view.rst +++ b/docs/source/ci/view.md @@ -1,13 +1,8 @@ -.. _glab_ci_view: - -glab ci view ------------- +## glab ci view View, run, trace/logs, and cancel CI jobs current pipeline -Synopsis -~~~~~~~~ - +### Synopsis Supports viewing, running, tracing, and canceling jobs. @@ -21,33 +16,30 @@ Use arrow keys to navigate jobs and logs. Supports vi style (hjkl,Gg) bindings and arrow keys for navigating jobs and logs. -:: - - glab ci view [branch/tag] [flags] +``` +glab ci view [branch/tag] [flags] +``` -Examples -~~~~~~~~ +### Examples -:: +``` +$ glab pipeline ci view # Uses current branch +$ glab pipeline ci view master # Get latest pipeline on master branch +$ glab pipeline ci view -b master # just like the second example +$ glab pipeline ci view -b master -R profclems/glab # Get latest pipeline on master branch of profclems/glab repo - $ glab pipeline ci view # Uses current branch - $ glab pipeline ci view master # Get latest pipeline on master branch - $ glab pipeline ci view -b master # just like the second example - $ glab pipeline ci view -b master -R profclems/glab # Get latest pipeline on master branch of profclems/glab repo - +``` -Options -~~~~~~~ - -:: +### Options +``` -b, --branch string Check pipeline status for a branch/tag. (Default is the current branch) +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command -R, --repo OWNER/REPO Select another repository using the OWNER/REPO or `GROUP/NAMESPACE/REPO` format or full URL or git URL +``` diff --git a/docs/source/completion/index.rst b/docs/source/completion/index.md similarity index 71% rename from docs/source/completion/index.rst rename to docs/source/completion/index.md index e228d5984e20041518ddc98c3f6f1241953ee2a3..7a83c2fddb959c9595007aa7f51f7c68747838d9 100755 --- a/docs/source/completion/index.rst +++ b/docs/source/completion/index.md @@ -1,13 +1,8 @@ -.. _glab_completion: - -glab completion ---------------- +## glab completion Generate shell completion scripts -Synopsis -~~~~~~~~ - +### Synopsis Generate shell completion scripts for glab commands. @@ -18,8 +13,8 @@ For example, for bash you could add this to your '~/.bash_profile': eval "$(glab completion -s bash)" -Generate a %[1]s_gh%[1]s completion script and put it somewhere in your %[1]s$fpath%[1]s: - gh completion -s zsh > /usr/local/share/zsh/site-functions/_gh +Generate a %[1]s_glab%[1]s completion script and put it somewhere in your %[1]s$fpath%[1]s: + glab completion -s zsh > /usr/local/share/zsh/site-functions/_glab Ensure that the following is present in your %[1]s~/.zshrc%[1]s: autoload -U compinit compinit -i @@ -31,22 +26,20 @@ no additional shell configuration is necessary to gain completion support. For Homebrew, see -:: - - glab completion [flags] +``` +glab completion [flags] +``` -Options -~~~~~~~ - -:: +### Options +``` --no-desc Do not include shell completion description -s, --shell string Shell type: {bash|zsh|fish|powershell} (default "bash") +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command +``` diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 54ad5694d1e7e5fc902a9d68b71c3a4b3eecd648..0000000000000000000000000000000000000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,72 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) -import sphinx_rtd_theme - -# -- Project information ----------------------------------------------------- - -project = 'GLab' -copyright = '2020, Clement Sam' -author = 'Clement Sam and contributors' - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx_rtd_theme", -] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -# html_theme = 'alabaster' -html_theme = "sphinx_rtd_theme" - -html_theme_options = { - 'canonical_url': '', - 'analytics_id': '', # Provided by Google in your dashboard - 'logo_only': True, - 'display_version': True, - 'prev_next_buttons_location': 'bottom', - 'style_external_links': True, - 'style_nav_header_background': 'white', - # Toc options - 'collapse_navigation': True, - 'sticky_navigation': True, - # 'navigation_depth': 4, - 'includehidden': True, - 'titles_only': False, -} - -html_logo = "_static/glab.png" -html_show_sourcelink = True -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -master_doc = 'index' diff --git a/docs/source/config/get.rst b/docs/source/config/get.md similarity index 51% rename from docs/source/config/get.rst rename to docs/source/config/get.md index 639d4c49ab40c6dd829c84d8425dbef9e3908797..1a9f618b62d6256d2975f76b82a04146f6a40d34 100644 --- a/docs/source/config/get.rst +++ b/docs/source/config/get.md @@ -1,44 +1,36 @@ -.. _glab_config_get: - -glab config get ---------------- +## glab config get Prints the value of a given configuration key -Synopsis -~~~~~~~~ - +### Synopsis Get the value for a given configuration key. -:: +``` +glab config get [flags] +``` - glab config get [flags] +### Examples -Examples -~~~~~~~~ +``` -:: + $ glab config get editor + vim + $ glab config get glamour_style + notty - - $ glab config get editor - vim - $ glab config get glamour_style - notty - +``` -Options -~~~~~~~ - -:: +### Options +``` -g, --global Read from global config file (~/.config/glab-cli/config.yml). [Default: looks through Environment variables → Local → Global] -h, --host string Get per-host setting +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command +``` diff --git a/docs/source/config/help.md b/docs/source/config/help.md new file mode 100644 index 0000000000000000000000000000000000000000..9b212a4ee56fcd7cc67d0749626ff4259e7f0ad6 --- /dev/null +++ b/docs/source/config/help.md @@ -0,0 +1,19 @@ +## glab config help + +Help about any command + +### Synopsis + +Help provides help for any command in the application. +Simply type config help [path to command] for full details. + +``` +glab config help [command] [flags] +``` + +### Options inherited from parent commands + +``` + --help Show help for command +``` + diff --git a/docs/source/config/help.rst b/docs/source/config/help.rst deleted file mode 100644 index b195dd36d510dd3a7954d207ea39294e747abd9b..0000000000000000000000000000000000000000 --- a/docs/source/config/help.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _glab_config_help: - -glab config help ----------------- - -Help about any command - -Synopsis -~~~~~~~~ - - -Help provides help for any command in the application. -Simply type config help [path to command] for full details. - -:: - - glab config help [command] [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: - - --help Show help for command - diff --git a/docs/source/config/index.rst b/docs/source/config/index.md similarity index 71% rename from docs/source/config/index.rst rename to docs/source/config/index.md index 29e9a18b919a9198961fda2da6f481dec3dca282..963b11ff2eee04f901e205131e1571b89c55cb74 100755 --- a/docs/source/config/index.rst +++ b/docs/source/config/index.md @@ -1,13 +1,8 @@ -.. _glab_config: - -glab config ------------ +## glab config Set and get glab settings -Synopsis -~~~~~~~~ - +### Synopsis Get and set key/value strings. @@ -19,31 +14,24 @@ Current respected settings: - editor: if unset, defaults to environment variables. - visual: alternative for editor. if unset, defaults to environment variables. - glamour_style: Your desired markdown renderer style. Options are dark, light, notty. Custom styles are allowed set a custom style https://github.com/charmbracelet/glamour#styles +- glab_pager: Your desired pager command to use (e.g. less -R) -Options -~~~~~~~ - -:: +### Options +``` -g, --global use global config file +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command +``` -Subcommands -~~~~~~~~~~~ -.. toctree:: - :glob: - :maxdepth: 0 - - get - init - set - +### Subcommands +- [get](get.md) +- [init](init.md) +- [set](set.md) diff --git a/docs/source/config/init.rst b/docs/source/config/init.md similarity index 56% rename from docs/source/config/init.rst rename to docs/source/config/init.md index 7943e86d79b9306ceadc314f0fc3ac9fe8f9d8ca..9c9f86f7f3d1288c543469ec5c296715ed4a896a 100644 --- a/docs/source/config/init.rst +++ b/docs/source/config/init.md @@ -1,13 +1,8 @@ -.. _glab_config_init: - -glab config init ----------------- +## glab config init Shows a prompt to set basic glab configuration -Synopsis -~~~~~~~~ - +### Synopsis Update the configuration by setting a key to a value. Examples: @@ -15,14 +10,13 @@ Examples: ? Enter default Gitlab Host (Current Value: https://gitlab.com): | -:: - - glab config init [flags] - -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +``` +glab config init [flags] +``` -:: +### Options inherited from parent commands +``` --help Show help for command +``` diff --git a/docs/source/config/set.rst b/docs/source/config/set.md similarity index 58% rename from docs/source/config/set.rst rename to docs/source/config/set.md index 33d638b1212a19cafdd5069e8866c19d3b772d59..0862c64d075e14384e54e4205b671004dd716788 100644 --- a/docs/source/config/set.rst +++ b/docs/source/config/set.md @@ -1,45 +1,37 @@ -.. _glab_config_set: - -glab config set ---------------- +## glab config set Updates configuration with the value of a given key -Synopsis -~~~~~~~~ - +### Synopsis Update the configuration by setting a key to a value. Use glab config set --global if you want to set a global config. Specifying the --hostname flag also saves in the global config file -:: +``` +glab config set [flags] +``` - glab config set [flags] +### Examples -Examples -~~~~~~~~ +``` -:: + $ glab config set editor vim + $ glab config set token xxxxx -h gitlab.com - - $ glab config set editor vim - $ glab config set token xxxxx -h gitlab.com - +``` -Options -~~~~~~~ - -:: +### Options +``` -g, --global write to global ~/.config/glab-cli/config.yml file rather than the repository .glab-cli/config/config -h, --host string Set per-host setting +``` -Options inherited from parent commands -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -:: +### Options inherited from parent commands +``` --help Show help for command +``` diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 0000000000000000000000000000000000000000..9787922cc80d1c7308af3b7c05251b73cfa02cf8 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,48 @@ +# GLab - A GitLab CLI Tool + +GLab is an open source Gitlab Cli tool written in Go (golang) to help +work seamlessly with Gitlab from the command line. Work with issues, +merge requests, **watch running pipelines directly from your CLI** among +other features. + +## Usage + +``` +glab [flags] +``` + +## Core Commands + + +- ``glab mr [list, create, close, reopen, delete, ...]`` +- ``glab issue [list, create, close, reopen, delete, ...]`` +- ``glab pipeline [list, delete, ci status, ci view, ...]`` +- ``glab release`` +- ``glab repo`` +- ``glab label`` +- ``glab alias`` + +### Examples + +``` +$ glab auth login --stdin < token.txt +$ glab issue list +$ glab mr for 123 # Create merge request for issue 123 +$ glab mr checkout 243 +$ glab pipeline ci view +$ glab mr view +$ glab mr approve +$ glab mr merge +``` + +## Installation + +You can find installation instructions on our [README](https://gitlab.com/gitlab-org/cli/#installation). + +## Authentication + +Run `glab auth login` to authenticate with your GitLab account. `glab` will respect tokens set using `GITLAB_TOKEN`. + +### Feedback + +Thank you for checking out GLab! Please open an [issue](https://gitlab.com/gitlab-org/cli/issues/new). to send us feedback. We're looking forward to hearing it. diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index aa5911ac1e0fd2358c726cae499552e9e772db64..0000000000000000000000000000000000000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. include:: ./intro.rst - -.. toctree:: - :hidden: - :glob: - :maxdepth: 1 - - Getting started - -.. toctree:: - :hidden: - :glob: - :maxdepth: 2 - :caption: Commands - - alias - auth - check-update - completion - config - issue - label