nprasad2077/docs
1
1
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-09-17 19:55:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add runner 2 and 3 documentations (#488)

Browse Source 
Reviewed-on: https://gitea.com/gitea/docs/pulls/488
Reviewed-by: silverwind <[email protected]>
This commit is contained in:
Lunny Xiao
2026-08-07 21:02:26 +00:00
parent 7629c02a9a
commit 0c62ec4893
57 changed files with 5215 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+44
View File
@@ -35,3 +35,47 @@ make update-api-docs-latest # refresh only static/swagger-latest.json
`static/swagger-latest.json` is refreshed automatically: the `update swagger files`
workflow runs every 12 hours and opens a pull request whenever gitea main changed.
Released versions are updated by hand when a new gitea version is documented.
## Runner docs
The runner documentation is a second docs plugin, served under `/runner`:
| Version | Content | URL |
| --- | --- | --- |
| develop | `runner-docs/` | `/runner/develop/` |
| current series | `runner-docs_versioned_docs/version-3/` | `/runner/` |
| older series | `runner-docs_versioned_docs/version-2/` | `/runner/2/` |
| archived series | `runner-docs_versioned_docs/version-1/` | `/runner/1/` |
A version directory covers a whole release series (`version-3` documents every
`3.x` release), so a patch release only needs a content update, not a new folder.
The UI labels a series `3.x`, derived from `runner-docs_versions.json`, so no
version number has to be bumped anywhere on a runner release. Use floating image
tags (`gitea/runner:3`) and links to the runner's `main` branch in those pages to
keep them valid across patch releases.
Its sidebar is written by hand: `runner-sidebars.js` for develop, and
`runner-docs_versioned_sidebars/version-<version>-sidebars.json` per documented
version. The version list lives in `runner-docs_versions.json`; the `versions`,
`lastVersion` and `Runner Version` dropdown entries in `docusaurus.config.js` are
built from it, so a new series only has to be cut with
`pnpm run docusaurus docs:version:runner-docs <series>`.
The pages under `reference/` are generated from the runner sources — the command
line reference from `--help`, the example configuration from `generate-config`:
```shell
make update-runner-docs # develop docs, from the main branch of gitea/runner
make update-runner-docs-released # every series, from its newest stable tag
./update_runner_docs.sh v3.0.2 runner-docs_versioned_docs/version-3/reference
```
`--released` (what `make update-runner-docs-released` runs) needs no version list:
it regenerates every `runner-docs_versioned_docs/version-<series>/reference`
directory from the newest stable `v<series>.x.y` tag of `gitea/runner`, looked up
through the Gitea API.
All of these pages are refreshed automatically: the `update runner reference`
workflow runs weekly, regenerates the develop and the released references, and
opens a pull request whenever the runner's CLI or example configuration changed.
Generating them needs Go, since the script builds the runner binary.