playground/docs-fp-o-ci-test
0
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Work in progress

Browse source 
Signed-off-by: Hristo Marinov <hricky@fedoraproject.org>
This commit is contained in:
Hristo Marinov 2026-08-24 01:05:16 +03:00
commit fd3f24d708
No known key found for this signature in database
1 changed files with 32 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

37
README.md
View file

@ -12,6 +12,12 @@ This is the build repository for the Fedora Documentation Website. Fedora Docs a
- **quay.io/fedora-docs/antora:latest**<br />
The image is built daily. It contains the Antora application and is used in the `docsbuilder.sh` script.
- **quay.io/fedora-docs/fedocs:latest**<br />
The image is built on push/PR and daily. It bundles `fedocs.py`, the watch/build/preview tool for a single Fedora Docs component repo — see [Previewing a single component](#previewing-a-single-component).
- **quay.io/fedora-docs/fedocs-cache:latest**<br />
The image is built hourly. It's not a runnable tool, just prefetched clones of every Fedora Docs component, mounted alongside `fedocs` at preview time so a fresh checkout doesn't need to clone ~50 repos on startup.
- **quay.io/fedora-docs/council-docs-test:latest**<br />
The image is built hourly. It contains the generated English Fedora Docs site and can be previewed by following the instructions in the [Previewing the site](#previewing-the-site) section.
@ -24,7 +30,7 @@ This is the build repository for the Fedora Documentation Website. Fedora Docs a
The images are signed using Cosign and can be verified by running the following command:
```text
just verify quay.io/fedora-docs/antora:latest
just verify-image quay.io/fedora-docs/antora:latest
```
To verify another image, replace `quay.io/fedora-docs/antora:latest` in the above command with any other image in the [Fedora Docs](https://quay.io/organization/fedora-docs) organization.
@ -33,7 +39,7 @@ To verify another image, replace `quay.io/fedora-docs/antora:latest` in the abov
To scan images for vulnerabilities using [Grype](https://anchore.com/grype/), run the following command:
```text
just scan quay.io/fedora-docs/antora:latest
just scan-image quay.io/fedora-docs/antora:latest
```
To scan another image, replace `quay.io/fedora-docs/antora:latest` in the above command with any other container image.
@ -45,7 +51,7 @@ To scan another image, replace `quay.io/fedora-docs/antora:latest` in the above
The following command builds the English documentation container image using the specified playbook file (defaults to `site.yml`).
```text
just build ./site-council-docs-test.yaml
just build-site ./site-council-docs-test.yaml
```
> [!NOTE]
@ -54,7 +60,7 @@ just build ./site-council-docs-test.yaml
> [!NOTE]
> The container build process uses multiple build stages, which can leave behind dangling images on your system. To clean these up, run:
> ```text
> just cleanup
> just cleanup-images
> ```
> The above command removes unused images and build cache, then displays the first 21 images on your system.
@ -63,9 +69,30 @@ just build ./site-council-docs-test.yaml
The following command runs the built container image and exposes the documentation site at http://localhost:8080 for local testing.
```text
just preview
just preview-site
```
### Previewing a single component
A single component repo (e.g. `council-docs-test`) doesn't need this repo's own `build-site`/`preview-site` — it pulls the already-published `fedocs`/`fedocs-cache` images instead. From that repo:
```text
just preview-components
```
This runs a live watch/rebuild preview server against the *real*, full cross-component playbook (every other Fedora Docs component already prefetched into `fedocs-cache`), so xrefs into other components resolve correctly from the first build. `fedocs`/`fedocs-cache` themselves are only built here, via:
```text
just build-fedocs
just build-fedocs-cache
```
`build-fedocs-cache` defaults to prefetching the real `site.yml`; pass `./site-council-docs-test.yaml` explicitly to match what the published, CI-built image (and `council-docs-test`'s own preview) actually uses.
### Per-PR previews
A component repo can also publish a live preview automatically on every pull request, via its own `.forgejo/workflows/pr-preview.yaml` (see `council-docs-test` for a working example) — built on top of the same `fedocs`/`fedocs-cache` images, published to a shared host. See this repo's `CLAUDE.md` ("PR preview pipeline for component repos") for how that pipeline actually works and the infrastructure it depends on.
## Documentation content
Documentation content is stored in multiple repositories listed in the `site.yml` file.