Lunny Xiao
0c62ec4893
Reviewed-on: https://gitea.com/gitea/docs/pulls/488 Reviewed-by: silverwind <[email protected]>
Gitea Docs 
How to build
make clean
make prepare-docs
make build
Development
make clean
make prepare-docs
make serve
Test en version
pnpm run start
API docs
The swagger definitions rendered under /api-docs live in static/swagger-latest.json
(gitea main) and static/swagger-<minor>.json (released versions).
make update-api-docs # refresh latest + every released version
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:
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.