From df0ad603a8b11de980ea44af37669216ccc6a8d2 Mon Sep 17 00:00:00 2001 From: "Benjamin R. J. Schwedler" Date: Thu, 12 Feb 2026 14:55:05 -0600 Subject: [PATCH] Improve cross-linking between different doc sources --- CI.md | 5 +++++ README.md | 9 ++++++--- posit-bakery/CONFIGURATION.md | 6 ++++++ posit-bakery/README.md | 12 ++++++++++-- posit-bakery/TEMPLATING.md | 6 ++++++ 5 files changed, 33 insertions(+), 5 deletions(-) diff --git a/CI.md b/CI.md index 346e9f8a..07524667 100644 --- a/CI.md +++ b/CI.md @@ -1,5 +1,10 @@ # Bakery CI +These workflows are used by the following product image repositories: +- [images-connect](https://github.com/posit-dev/images-connect) +- [images-package-manager](https://github.com/posit-dev/images-package-manager) +- [images-workbench](https://github.com/posit-dev/images-workbench) + ## Shared Workflows This repository provides two Github Action workflows for building, testing, and pushing images: diff --git a/README.md b/README.md index 46072fd4..c0d00e37 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,9 @@ | Repository | Description | |:-----------|:------------| | [images](https://github.com/posit-dev/images) | Posit Container Image Meta Repository | -| `images-connect` | Posit Connect Container Images | +| [images-connect](https://github.com/posit-dev/images-connect) | Posit Connect Container Images | | [images-package-manager](https://github.com/posit-dev/images-package-manager) | Posit Package Manager Container Images | -| `images-workbench` | Posit Workbench Container Images | +| [images-workbench](https://github.com/posit-dev/images-workbench) | Posit Workbench Container Images | | [images-examples](https://github.com/posit-dev/images-examples) | Examples for using and extending Posit Container Images | ## Tools @@ -22,10 +22,13 @@ The [bakery](./posit-bakery/) command line interface (CLI) binds together various [tools](./posit-bakery/README.md#3rd-party-tools) to managed a matrix of container image builds. >[!TIP] -> [Get started with `bakery`](./posit-bakery/README.md#getting-started) +> - [Get started with `bakery`](./posit-bakery/README.md#getting-started) +> - [Bakery Examples](https://github.com/posit-dev/images-examples/tree/main/bakery) — step-by-step tutorials ## GitHub Actions +See [CI Workflows](./CI.md) for shared GitHub Actions workflows used by product image repositories. + ### setup-goss Bakery uses [goss](https://github.com/goss-org/goss) and [dgoss](https://github.com/goss-org/goss/tree/master/extras/dgoss) to define and execute tests that ensure that the container image was built properly. diff --git a/posit-bakery/CONFIGURATION.md b/posit-bakery/CONFIGURATION.md index c4e866b5..19ce06ba 100644 --- a/posit-bakery/CONFIGURATION.md +++ b/posit-bakery/CONFIGURATION.md @@ -534,3 +534,9 @@ A GossOption represents options for `dgoss` tests against an image target. | `runtimeOptions`
*string* | Additional runtime options to pass to the `dgoss` container instantiation when running tests. | | `--privileged` | | `command`
*string* | | The command to run within the `dgoss` container. This can be used to start a service in the container for testing. | `sleep infinity` | `start-server` | | `wait`
*int* | The number of seconds to wait after container startup before running tests. Useful if there is a service that needs to complete its startup prior to testing. | `0` | `30` | + +## See Also + +- [Templating Documentation](./TEMPLATING.md) — Jinja2 macros and variables available in image templates +- [Architecture Diagrams](./ARCHITECTURE.md) — Detailed tool behavior and flow diagrams +- [Bakery Examples](https://github.com/posit-dev/images-examples/tree/main/bakery) — Real-world `bakery.yaml` files and step-by-step tutorials diff --git a/posit-bakery/README.md b/posit-bakery/README.md index 55565dbb..a6e0237e 100644 --- a/posit-bakery/README.md +++ b/posit-bakery/README.md @@ -41,6 +41,14 @@ The [bakery](./posit-bakery/) command line interface (CLI) binds together variou pipx install 'git+https://github.com/posit-dev/images-shared.git@main#subdirectory=posit-bakery&egg=posit-bakery' ``` +## Examples + +See the [Bakery Examples](https://github.com/posit-dev/images-examples/tree/main/bakery) repository for step-by-step tutorials on creating and managing container image projects with Bakery. + +## CI Integration + +Bakery provides shared GitHub Actions workflows for building, testing, and pushing images. See the [CI Workflows](../CI.md) documentation for usage details. + ## Usage >[!TIP] @@ -159,7 +167,7 @@ bakery help bakery run dgoss ``` - Additional run options can be specified using Goss options in `bakery.yaml` on a per image or per variant basis + Additional run options can be specified using [Goss options](./CONFIGURATION.md#gossoptions) in `bakery.yaml` on a per image or per variant basis ## Bakery Concepts @@ -176,7 +184,7 @@ bakery --context /path/to/directory ``` A bakery **project** can include one or more **image**s. -Each **image** can optionally have one or more **variant**s. By default, there are two variants: Standard and Minimal. +Each **image** can optionally have one or more [**variant**](./CONFIGURATION.md#imagevariant)s. By default, there are two variants: Standard and Minimal. Each **image** should have one or more **version**s. Each **version** can have one or more **OS**es. diff --git a/posit-bakery/TEMPLATING.md b/posit-bakery/TEMPLATING.md index 5b990690..a96dcce4 100644 --- a/posit-bakery/TEMPLATING.md +++ b/posit-bakery/TEMPLATING.md @@ -470,3 +470,9 @@ To wrap `install()` in a Docker RUN statement, use: ```jinja2 {{ waitforit.run_install() }} ``` + +## See Also + +- [Configuration Documentation](./CONFIGURATION.md) — `bakery.yaml` schema reference +- [Architecture Diagrams](./ARCHITECTURE.md) — Detailed tool behavior and flow diagrams +- [Bakery Examples](https://github.com/posit-dev/images-examples/tree/main/bakery) — Step-by-step tutorials, including the managed dependencies and matrix images examples