From 8594d73ccdf5715e6b856134fb29e4c53bdc6e68 Mon Sep 17 00:00:00 2001 From: silverwind Date: Thu, 22 Oct 2026 22:06:45 +0200 Subject: [PATCH] docs: tighten the gt guides and the cli wiring The workflow example had no trigger, so Gitea would reject it as written. The guides now merge the small account sections and point users at the nightly builds they describe. Comments and READMEs no longer mention the dropped reference generator or list the runner as the only hand written sidebar product, and the sidebar lookup drops a key the fallback covers. Co-Authored-By: Claude (Opus 5.5) --- README.md | 19 ++++++------------- cli-docs/authentication.md | 20 +++++++++----------- cli-docs/ci.md | 8 ++++++-- cli-docs/index.md | 7 +++---- packages/content-loader/src/products.ts | 11 ++++------- packages/content-loader/src/sidebar.ts | 6 +++--- sites/docs/README.md | 20 ++++++++++---------- sites/docs/src/integrations/postbuild.ts | 6 +++--- sites/docs/src/lib/pagefind-ui.ts | 2 +- sites/docs/src/lib/sidebars.ts | 2 +- 10 files changed, 46 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 7791b16b..39bba953 100644 --- a/README.md +++ b/README.md @@ -120,19 +120,12 @@ the runner binary. ## CLI docs The documentation of `gt`, the Gitea CLI from -[gitea/cli](https://gitea.com/gitea/cli), is laid out like the runner docs: - -| Version | Content | URL | -| --- | --- | --- | -| develop | `cli-docs/` | `/cli/` until the first release, then `/cli/develop/` | -| current series | `cli-docs_versioned_docs/version-/` | `/cli/` | -| older series | `cli-docs_versioned_docs/version-/` | `/cli//` | - -No series is documented yet. Once a release exists, cut its series with -`make cut-version PRODUCT=cli VERSION=0.1`, then list it in `cliSeries` in -`packages/content-loader/src/products.ts`; the develop docs then move to -`/cli/develop/`. Its sidebar is written by hand in `cli-sidebars.js`. The -guides do not repeat every flag: `gt --help` documents each command. +[gitea/cli](https://gitea.com/gitea/cli), is laid out like the runner docs, with +its sidebar in `cli-sidebars.js`. No series is documented yet, so `cli-docs/` is +served at `/cli/`. Once a release exists, cut its series and list it in +`cliSeries` in `packages/content-loader/src/products.ts`, which moves the develop +docs to `/cli/develop/`. The guides leave the flags of each command to +`gt --help`. ## Deployment diff --git a/cli-docs/authentication.md b/cli-docs/authentication.md index fef78fbb..f2c10ad7 100644 --- a/cli-docs/authentication.md +++ b/cli-docs/authentication.md @@ -38,20 +38,18 @@ token: gt auth login --host https://gitea.example.com --ssh-key ~/.ssh/id_ed25519 ``` -## Where credentials are kept +## Accounts -Tokens go to the system keyring by default. `--credential-store file` keeps them in gt's -configuration directory instead, for machines without a keyring. `gt auth status` lists -your accounts and `gt auth logout` removes one. +Tokens go to the system keyring, or with `--credential-store file` to gt's configuration +directory on machines without one. Run `gt auth login` once per instance and account. +gt picks the instance from the repository's remote or `--host`, and the account with +`gt auth switch` or `--user`. `gt auth status` lists your accounts and `gt auth logout` +removes one. + +For instances behind an access proxy, `--header` and `--client-cert` add headers and a +client certificate. ## Git over HTTPS `gt auth setup-git` lets `git push` and `git fetch` over HTTPS use gt's login. gt's own clone and checkout commands need no setup. - -## Several instances and accounts - -Run `gt auth login` for each instance and account. gt picks the instance from the -repository's remote or `--host`, and the account with `gt auth switch` or `--user`. -For instances behind an access proxy, `--header` and `--client-cert` add headers and a -client certificate; see `gt auth login --help`. diff --git a/cli-docs/ci.md b/cli-docs/ci.md index 97436605..c11aa356 100644 --- a/cli-docs/ci.md +++ b/cli-docs/ci.md @@ -21,8 +21,12 @@ Gitea does not allow secret names that start with `GITEA_`, so store the token a example, `GT_TOKEN`: ```yaml +on: + push: + branches: [main] + jobs: - deploy: + staging: runs-on: ubuntu-latest env: GITEA_TOKEN: ${{ secrets.GT_TOKEN }} @@ -33,4 +37,4 @@ jobs: - run: gt workflow run deploy.yml --ref main --field env=staging --no-input ``` -`gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when they do. +`gt run watch` and `gt pr checks --watch` wait for runs and checks and fail when one fails. diff --git a/cli-docs/index.md b/cli-docs/index.md index de9bb963..9c5b2ba6 100644 --- a/cli-docs/index.md +++ b/cli-docs/index.md @@ -10,7 +10,7 @@ with repositories, issues, pull requests, releases, Actions and the other resour Gitea instance, from a terminal or a script. :::info Development version -These pages describe builds from the `main` branch of gitea/cli. +These pages describe builds from the `main` branch, published as `nightly` binaries and images. ::: gt needs Gitea 28 or later, and Git for the commands that clone, check out or push. @@ -34,6 +34,5 @@ gt needs Gitea 28 or later, and Git for the commands that clone, check out or pu `gt doctor` checks your setup and suggests a fix for each problem it finds. -Every command documents itself with `--help`. `gt help environment`, `gt help formatting` -and `gt help exit-codes` cover global flags and environment variables, JSON output, and -exit codes. +`gt --help` lists the flags of a command, and `gt help environment` the global +flags and environment variables. diff --git a/packages/content-loader/src/products.ts b/packages/content-loader/src/products.ts index e2e3160d..725d8f8b 100644 --- a/packages/content-loader/src/products.ts +++ b/packages/content-loader/src/products.ts @@ -247,13 +247,10 @@ const runnerProduct: ProductDef = { }; /** - * gt, the Gitea CLI: one directory per release series, english only, like the - * runner. The label is the newest release of the series, which is also the tag - * the generated reference pages of that directory come from. - * - * Until the first series is listed here the develop docs are served at the - * product root, without the unreleased banner, since there is no release to - * point to. Listing a series moves them to `/cli/develop/`. + * gt, the Gitea CLI: laid out like the runner. Until the first series is listed + * here the develop docs are served at the product root, without the unreleased + * banner, since there is no release to point to. Listing a series moves them to + * `/cli/develop/`. */ const cliSeries: { id: string; latestRelease: string }[] = []; diff --git a/packages/content-loader/src/sidebar.ts b/packages/content-loader/src/sidebar.ts index 2770e4b3..08b142f9 100644 --- a/packages/content-loader/src/sidebar.ts +++ b/packages/content-loader/src/sidebar.ts @@ -1,7 +1,7 @@ /** * Builds one sidebar per (product, version, language) out of the loaded pages, * deriving it from `_category_.json` and from the - * handwritten sidebar files of the runner docs. + * handwritten sidebar files of the runner and the cli docs. */ import { defaultLocale } from './products'; @@ -44,7 +44,7 @@ export interface SidebarGroup { export type SidebarEntry = SidebarLink | SidebarGroup; -/** A hand written sidebar file, as used by the runner docs. */ +/** A hand written sidebar file, as used by the runner and the cli docs. */ export type SidebarSourceItem = | string | { type: 'doc'; id: string; label?: string } @@ -148,7 +148,7 @@ function treeOf(pages: SidebarPage[]): Tree { return { build, label }; } -/** Sidebar described by a hand written sidebar file, used by the runner docs. */ +/** Sidebar described by a hand written sidebar file, used by the runner and the cli docs. */ function fromSidebarSource( items: SidebarSourceItem[], pages: SidebarPage[], diff --git a/sites/docs/README.md b/sites/docs/README.md index aa767f31..8d5bf9fc 100644 --- a/sites/docs/README.md +++ b/sites/docs/README.md @@ -1,15 +1,15 @@ # Astro + Starlight site Renders the gitea documentation with [Starlight](https://starlight.astro.build): -the docs (6 versions x 3 languages), the runner docs (4 series), the gt (Gitea -CLI) docs and the api reference (7 swagger documents). The enterprise docs stay in their own -deployment and are linked from the header. +the docs (6 versions x 3 languages), the runner docs (4 series), the cli docs +and the api reference (7 swagger documents). The enterprise docs stay in their +own deployment and are linked from the header. The content directories are the ones the site has always used — `docs/`, -`versioned_docs/`, `i18n/`, `runner-docs/`, `runner-docs_versioned_docs/`, -`cli-docs/` and +`versioned_docs/`, `i18n/`, `runner-docs/`, `runner-docs_versioned_docs/` and `static/swagger-*.json` (plus `static/openapi3-*.json` since gitea 1.27) — so -the release scripts and the translation workflow stay unchanged. +the release scripts and the translation workflow stay unchanged. The cli docs +in `cli-docs/` follow the layout of the runner docs. ## Running it @@ -74,10 +74,10 @@ instead of warning. The docs are the site itself, so their language comes first: `/zh-cn/1.26/`. The runner, the cli and the api are separate products and keep their language inside the product, `/runner/zh-cn/3/`, which is reserved: all are published in -english only today. Starlight builds a fallback page in every configured language for -every english page, so `/zh-cn/runner/` would exist; the post build integration -removes those directories and `cloudflare/_redirects` sends them to the -english page. +english only today. Starlight builds a fallback page in every configured +language for every english page, so `/zh-cn/runner/` would exist; the post build +integration removes those directories and `cloudflare/_redirects` sends them to +the english page. The version served at the root of a product has no number in its url: docs 1.27 is `/`, runner 3 is `/runner/` and api 1.27 is `/api/`. `/1.27/`, `/runner/3/` diff --git a/sites/docs/src/integrations/postbuild.ts b/sites/docs/src/integrations/postbuild.ts index 513fdf9d..c1489a45 100644 --- a/sites/docs/src/integrations/postbuild.ts +++ b/sites/docs/src/integrations/postbuild.ts @@ -11,9 +11,9 @@ import { defaultLocale, locales, products, type LocaleId } from '@gitea-docs/con * generated as `/api/126/`. The directories are renamed and the links inside * the build are rewritten. * - starlight builds a fallback page in every configured language for every - * english page. That is what we want for the docs, but the runner and the api - * are separate products with their own language list, so `/zh-cn/runner/` has - * to go; `cloudflare/_redirects` sends it to the english page. + * english page. That is what we want for the docs, but the other products + * have their own language list, so `/zh-cn/runner/` has to go; + * `cloudflare/_redirects` sends it to the english page. */ export function giteaPostBuild(): AstroIntegration { return { diff --git a/sites/docs/src/lib/pagefind-ui.ts b/sites/docs/src/lib/pagefind-ui.ts index ff031cb2..c184f0a6 100644 --- a/sites/docs/src/lib/pagefind-ui.ts +++ b/sites/docs/src/lib/pagefind-ui.ts @@ -90,7 +90,7 @@ function addScopeToggle(root: HTMLElement, onChange: (allVersions: boolean) => v /** * While all versions are searched the same page shows up once per version, so - * the version (and the product, for the api and the runner) is appended to the + * the version (and the product, for every product but the docs) is appended to the * title of a result. */ function labelResult(result: PagefindResult): void { diff --git a/sites/docs/src/lib/sidebars.ts b/sites/docs/src/lib/sidebars.ts index 70c44446..d185b6f6 100644 --- a/sites/docs/src/lib/sidebars.ts +++ b/sites/docs/src/lib/sidebars.ts @@ -53,7 +53,7 @@ function sidebarSources(): Map { for (const [key, file] of Object.entries(files)) { const config = read(file); - const items = config && (config.docs ?? config.runner ?? config.cli ?? Object.values(config)[0]); + const items = config && (config.docs ?? config.runner ?? Object.values(config)[0]); if (items) sidebars.set(key, items); } return sidebars;