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;