From 622b87689ca30050859f51089c5b3ef4242523cd Mon Sep 17 00:00:00 2001 From: "Benjamin R. J. Schwedler" Date: Wed, 28 Jan 2026 15:35:22 -0600 Subject: [PATCH] Ensure docs use posit style. --- posit-bakery/CLAUDE.md | 3 +-- posit-bakery/CONFIGURATION.md | 32 +++++++++++++++----------------- posit-bakery/README.md | 16 ++++++++-------- posit-bakery/TEMPLATING.md | 22 ++++++++++------------ 4 files changed, 34 insertions(+), 39 deletions(-) diff --git a/posit-bakery/CLAUDE.md b/posit-bakery/CLAUDE.md index 79942634..d167d6a0 100644 --- a/posit-bakery/CLAUDE.md +++ b/posit-bakery/CLAUDE.md @@ -4,8 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -Posit Bakery is a command-line tool for building, testing, and managing containerized images. It provides a structured approach to create, build, and test Docker images with variant support (e.g., Standard vs Minimal), - + version management, OS variants, and dependency constraints. +Posit Bakery provides a command-line tool for building, testing, and managing containerized images. It offers a structured approach to create, build, and test Docker images with variant support (e.g., Standard vs Minimal), version management, OS variants, and dependency constraints. The tool uses a YAML configuration file (`bakery.yaml`) and Jinja2 templates to define image builds, with support for parallel building via Docker Buildx Bake. diff --git a/posit-bakery/CONFIGURATION.md b/posit-bakery/CONFIGURATION.md index 76798710..59905af8 100644 --- a/posit-bakery/CONFIGURATION.md +++ b/posit-bakery/CONFIGURATION.md @@ -1,6 +1,6 @@ # Configuration Overview -This document provides an overview of the configuration schema for Bakery, a tool for managing container images. The configuration is defined in a YAML file named `bakery.yaml`. A template for this file can be created using `bakery create project`. +This document provides an overview of the configuration schema for Bakery, a tool for managing container images. You define the configuration in a YAML file named `bakery.yaml`. Create a template for this file using `bakery create project`. Fields marked as "*Required*" must be provided in the configuration file. @@ -117,8 +117,7 @@ images: ### Repository -A Repository stores the metadata of the parent source code repository of the project. It is primarily used -for labeling images. +A Repository stores the metadata of the parent source code repository of the project. Bakery primarily uses it for labeling images. | Field | Description | Default Value | Example | |-----------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|---------------------------------------|---------------------------------------------------------------------------------------------------| @@ -138,9 +137,9 @@ A BaseRegistry represents a container image registry. It does not specify the re ### Registry -A Registry represents a container image registry and includes the name or repository of the image. It is a subclass of BaseRegistry. +A Registry represents a container image registry and includes the name or repository of the image. Registry extends BaseRegistry. -This type can be specified for an image or version, but cannot be specified at the top level of the bakery configuration. +You can specify this type for an image or version, but you cannot specify it at the top level of the bakery configuration. A common use is pushing images to a repository name that is different from the name of the image. @@ -154,7 +153,7 @@ A common use is pushing images to a repository name that is different from the n ### Image -An Image represents a container image managed by the project. Each image has one or more versions and optionally can have one or more variants and operating systems. New images can be created using the `bakery create image` command. +An Image represents a container image managed by the project. Each image has one or more versions and optionally can have one or more variants and operating systems. Create new images using the `bakery create image` command. | Field | Description | Default Value | Example | |-----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|-------------------------------------------------------------------------------------------------------| @@ -231,8 +230,7 @@ images: ### ImageVariant -An ImageVariant represents a variant of an image, such as standard or minimal builds. Each variant is expected have its -own `Containerfile..`. +An ImageVariant represents a variant of an image, such as standard or minimal builds. Each variant should have its own `Containerfile..`. | Field | Description | Default Value | Example | |--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------| @@ -245,7 +243,7 @@ own `Containerfile..`. #### Common Image Variants -By default, the image variants for an [Image](#image) will be set to an empty list `[]` f no `variants` are otherwise specified for the [Image](#image). +By default, Bakery sets the image variants for an [Image](#image) to an empty list `[]` if you do not specify `variants` for the [Image](#image). A common pattern is to build a minimal image containing fewer dependencies, and a standard image that builds dependencies into the container. @@ -262,9 +260,9 @@ variants: ### DependencyConstraint -Dependencies represents a list software dependencies that is installed in a specific image. +Dependencies represent software that Bakery installs in a specific image. -At the image level, these are specified through a VersionConstraint. +At the image level, you specify these through a VersionConstraint. | Field | Description | Default Value | Example | |-------|-------------|---------------|---------| @@ -283,7 +281,7 @@ The versions can be defined explicitly as an array of strings, or in terms of a | `max`
*string* | Maximum version to include. | | `3.13.7`, `3.11`, `3` | | `min`
*string* | Minimum version to include. | | `4.2.1`, `4.3`, `4` | -At least one of `latest` or `max` must be specified. +You must specify at least one of `latest` or `max`. If `latest` is `true` and no other fields are set, `count` defaults to `1`. @@ -311,7 +309,7 @@ dependencyConstraints: ### ImageVersion -An ImageVersion represents a specific version of an image. Each version should be rendered from templates using the `bakery create version` command. +An ImageVersion represents a specific version of an image. Render each version from templates using the `bakery create version` command. | Field | Description | Default Value | Example | |-----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| @@ -365,9 +363,9 @@ os: ### DependencyVersions -Dependencies represents a list software dependencies that is installed in a specific image. +Dependencies represent software that Bakery installs in a specific image. -At the image level, these are specified by an array of strings. +At the image level, you specify these as an array of strings. | Field | Description | Default Value | Example | |-------|-------------|---------------|---------| @@ -405,7 +403,7 @@ A NameEmail represents a name and email address pair. ### TagPattern -A TagPattern represents a pattern for tagging images. It can include placeholders that are replaced with actual values when generating tags. +A TagPattern represents a pattern for tagging images. It can include placeholders that Bakery replaces with actual values when generating tags. | Field | Description | |----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -414,7 +412,7 @@ A TagPattern represents a pattern for tagging images. It can include placeholder #### Pattern Templating -All [TagPattern](#tagpattern) `patterns` should be valid Jinja2 template strings. +All [TagPattern](#tagpattern) `patterns` must be valid Jinja2 template strings. The following variables are available for use in `patterns`: - `{{ Version }}`: The version of the image. diff --git a/posit-bakery/README.md b/posit-bakery/README.md index 55565dbb..41736dd4 100644 --- a/posit-bakery/README.md +++ b/posit-bakery/README.md @@ -56,7 +56,7 @@ bakery --help bakery help ``` -### Step 1. Create a project +### Step 1. Create a project {#create-project} * Create a new project @@ -64,7 +64,7 @@ bakery help bakery create project ``` - This command will create a new project configuration file in the bakery context. + This command creates a new project configuration file in the bakery context. * Make changes to the `bakery.yaml` file @@ -74,7 +74,7 @@ bakery help * Document the source code [Repository](./CONFIGURATION.md#repository) * Configure image [Registry](./CONFIGURATION.md#registry) entries to tag and push images to specific registries -### Step 2. Create an image +### Step 2. Create an image {#create-image} * Create a new image @@ -108,7 +108,7 @@ bakery help Template files must end with the `.jinja2` file extension. -### Step 3. Create an image version +### Step 3. Create an image version {#create-image-version} * Create a new version of the image @@ -135,7 +135,7 @@ bakery help * Set [Dependency Versions](./CONFIGURATION.md#dependencyversions) -### Step 4. Build the image(s) +### Step 4. Build the image(s) {#build-images} * Preview the [bake plan](https://docs.docker.com/build/bake/reference/) [OPTIONAL] @@ -151,7 +151,7 @@ bakery help bakery build ``` -### Step 5. Run the tests +### Step 5. Run the tests {#run-tests} * Run the `dgoss` tests against all the images @@ -159,14 +159,14 @@ 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 + You can specify additional run options using Goss options in `bakery.yaml` on a per image or per variant basis. ## Bakery Concepts ### Project Structure Bakery establishes a directory structure, referred to as a **project**. -The **project** configuration is stored in the `bakery.yaml`. +The `bakery.yaml` file stores the **project** configuration. By default, bakery uses the invocation directory as the project **context**. You can use the `--context` flag to override the default behavior. diff --git a/posit-bakery/TEMPLATING.md b/posit-bakery/TEMPLATING.md index 7e91be23..a6c4e6c5 100644 --- a/posit-bakery/TEMPLATING.md +++ b/posit-bakery/TEMPLATING.md @@ -3,7 +3,7 @@ This document outlines the available Jinja2 macros in the Posit Bakery templating system for creating Docker images with package installations. -Macros must be explicitly imported in every file in which they are used. +You must explicitly import macros in every file where you use them. References: - [Source Code](./posit_bakery/config/templating/macros) @@ -20,10 +20,10 @@ References: - [Quarto Installation and Management](#quarto-installation-and-management) ## Available Variables -The following variables are available by default for use in an image's Jinja2 templates. Additional values passed using -`--value` to `bakery create` or specified in the `values` field of an image version will also be available. +You can use the following variables by default in an image's Jinja2 templates. Additional values passed using +`--value` to `bakery create` or specified in the `values` field of an image version are also available. -Currently, `Containerfile` templates render as a unique file for each variant and OS. Using variant and OS based Jinja2 conditionals outside of `Containerfile` templates is not currently supported and will lead to unexpected results or errors. +Currently, `Containerfile` templates render as a unique file for each variant and OS. Bakery does not currently support using variant and OS based Jinja2 conditionals outside of `Containerfile` templates, and doing so leads to unexpected results or errors. - `Image`: A dictionary containing information about the current image, version, variant, and OS. - `Image.Name`: The name field of the image, e.g. `package-manager`, `workbench`, `connect`. @@ -74,7 +74,7 @@ To wrap `setup()` in a Docker RUN statement, use: #### Setup Posit Cloudsmith Apt Repositories Renders commands to set up Posit Cloudsmith apt repositories. Requires `curl` to be installed prior to execution. -**NOTE:** This macro is included in `apt.setup()` or `apt.run_setup()`, so it does not need to be called separately unless `apt.setup()` is not used. +**NOTE:** `apt.setup()` and `apt.run_setup()` include this macro, so you do not need to call it separately unless you skip `apt.setup()`. ```jinja2 {{ apt.setup_posit_cloudsmith() }} @@ -87,8 +87,7 @@ To wrap `setup_posit_cloudsmith()` in a Docker RUN statement, use: ``` #### Apt Clean Commands -Renders commands to clean and remove the apt cache to ensure minimal image layers. Clean commands should be run at the end of any RUN -statement that modifies packages, but it is implicitly included in most other macros that modify packages. +Renders commands to clean and remove the apt cache to ensure minimal image layers. Run clean commands at the end of any RUN statement that modifies packages. Most other macros that modify packages implicitly include clean commands. ```jinja2 {{ apt.clean_command() }} @@ -97,7 +96,7 @@ statement that modifies packages, but it is implicitly included in most other ma #### Apt Update and Upgrade Renders commands to update the apt cache, upgrade packages, run dist-upgrade, and remove unneeded packages. Pass `False` to the `clean` argument to skip cleaning the cache if you want to append additional commands. Clean is `True` by default. -**NOTE:** This macro is called by `apt.setup()` and `apt.run_setup()`, so it does not need to be called separately unless `apt.setup()` is not used. +**NOTE:** `apt.setup()` and `apt.run_setup()` call this macro, so you do not need to call it separately unless you skip `apt.setup()`. ```jinja2 {{ apt.update_upgrade(clean = True) }} @@ -154,7 +153,7 @@ To wrap `setup()` in a Docker RUN statement, use: #### Setup Posit Cloudsmith DNF Repositories Renders commands to set up Posit Cloudsmith DNF repositories. Requires `curl` to be installed prior to execution. -**NOTE:** This macro is included in `dnf.setup()` or `dnf.run_setup()`, so it does not need to be called separately unless `dnf.setup()` is not used. +**NOTE:** `dnf.setup()` and `dnf.run_setup()` include this macro, so you do not need to call it separately unless you skip `dnf.setup()`. ```jinja2 {{ dnf.setup_posit_cloudsmith() }} @@ -167,8 +166,7 @@ To wrap `setup_posit_cloudsmith()` in a Docker RUN statement, use: ``` #### DNF Clean Command -Renders commands to clean the dnf package cache. Clean commands should be run at the end of any RUN -statement that modifies packages, but it is implicitly included in most other macros that modify packages. +Renders commands to clean the dnf package cache. Run clean commands at the end of any RUN statement that modifies packages. Most other macros that modify packages implicitly include clean commands. ```jinja2 {{ dnf.clean_command() }} @@ -177,7 +175,7 @@ statement that modifies packages, but it is implicitly included in most other ma #### DNF Update and Upgrade Renders commands to upgrade packages, remove unneeded packages, and clean the cache. Pass `False` to the `clean` argument to skip cleaning the cache if you want to append additional commands. Clean is `True` by default. -**NOTE:** This macro is called by `dnf.setup()` and `dnf.run_setup()`, so it does not need to be called separately unless `dnf.setup()` is not used. +**NOTE:** `dnf.setup()` and `dnf.run_setup()` call this macro, so you do not need to call it separately unless you skip `dnf.setup()`. ```jinja2 {{ dnf.update_upgrade(clean = True) }}