# Gitea Docs ![badge](https://gitea.com/gitea/docs/actions/workflows/build-and-publish.yaml/badge.svg)

## 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.