mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-17 19:55:34 +00:00
Lunny Xiao
0c62ec4893
Reviewed-on: https://gitea.com/gitea/docs/pulls/488 Reviewed-by: silverwind <[email protected]>
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
# Gitea Docs 
|
|
|
|
## How to build
|
|
|
|
```shell
|
|
make clean
|
|
make prepare-docs
|
|
make build
|
|
```
|
|
|
|
## Development
|
|
|
|
```shell
|
|
make clean
|
|
make prepare-docs
|
|
make serve
|
|
```
|
|
|
|
## Test en version
|
|
|
|
```shell
|
|
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).
|
|
|
|
```shell
|
|
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`:
|
|
|
|
```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.
|