Changes to builder doc

More corrections

Improve EE documentation

https://issues.redhat.com/browse/AAP-24985

downstream/assemblies/builder/assembly-definition-file-breakdown.adoc

@@ -13,6 +13,7 @@ include::builder/con-galaxy-dependencies.adoc[leveloffset=+2]
 include::builder/con-python-dependencies.adoc[leveloffset=+2]
 include::builder/con-system-dependencies.adoc[leveloffset=+2]
 include::builder/ref-definition-file-images.adoc[leveloffset=+1]
+include::builder/ref-example-file-to-build-image.adoc[leveloffset=+2]
 include::builder/con-additional-build-files.adoc[leveloffset=+1]
 include::builder/con-additional-custom-build-steps.adoc[leveloffset=+1]
 

downstream/modules/builder/con-additional-build-files.adoc

@@ -7,10 +7,11 @@ You can add any external file to the build context directory by referring or cop
 Each list item must be a dictionary containing the following required keys:
 
 `src`:: Specifies the source files to copy into the build context directory. This can be an absolute path (for example, `/home/user/.ansible.cfg`), or a path that is relative to the {ExecEnvShort} file. Relative paths can be glob expressions matching one or more files (for example, `files/*.cfg`).
-
++
 [NOTE]
 ====
-Absolute paths can not include a regular expression. If `src` is a directory, the entire contents of that directory are copied to `dest`.
+Absolute paths can not include a regular expression. 
+If `src` is a directory, the entire contents of that directory are copied to `dest`.
 ====
 
 `dest`:: Specifies a subdirectory path underneath the `_build` subdirectory of the build context directory that contains the source files (for example, `files/configs`). This can not be an absolute path or contain `..` within the path. {Builder} creates this directory for you if it does not already exist.

downstream/modules/builder/con-additional-custom-build-steps.adoc

@@ -2,39 +2,41 @@
 
 = Additional custom build steps
 
-You can specify custom build commands for any build phase in the `additional_build_steps` section of the definition file. This allows fine-grained control over the build phases.
+You can specify custom build commands for any build phase in the `additional_build_steps` section of the definition file. 
+This enables fine-grained control over the build phases.
 
-Use the `prepend_` and `append_` commands to add directives to the `Containerfile` that run either before or after the main build steps are executed. The commands must conform to any rules required for the runtime system.
+Use the `prepend_` and `append_` commands to add directives to the `Containerfile` that run either before or after the main build steps are executed. 
+The commands must conform to any rules required for the runtime system.
 
-See the following table for a list of values that can be used in `additional_build_steps`:
+The following table shows a list of values that can be used in `additional_build_steps`:
 
 [cols="a,a"]
 |===
 | Value | Description
 
 | `prepend_base`
-| Allows you to insert commands before building the base image.
+| Enables you to insert commands before building the base image.
 
 | `append_base`
-| Allows you to insert commands after building the base image.
+| Enables you to insert commands after building the base image.
 
 | `prepend_galaxy`
-| Allows you to insert before building the galaxy image.
+| Enables you to insert before building the galaxy image.
 
 | `append_galaxy`
-| Allows you to insert after building the galaxy image.
+| Enables you to insert after building the galaxy image.
 
 | `prepend_builder`
-| Allows you to insert commands before building the Python builder image.
+| Enables you to insert commands before building the Python builder image.
 
 | `append_builder`
-| Allows you to insert commands after building the Python builder image.
+| Enables you to insert commands after building the Python builder image.
 
 | `prepend_final`
-| Allows you to insert before building the final image.
+| Enables you to insert before building the final image.
 
 | `append_final`
-| Allows you to insert after building the final image.
+| Enables you to insert after building the final image.
 
 |===
 

downstream/modules/builder/con-building-definition-file.adoc

@@ -2,7 +2,8 @@
 
 = Building a definition file
 
-After you install {Builder}, you can create a definition file that defines what {Builder} uses to create your {ExecEnvNameSing} image. {Builder} makes an {ExecEnvNameSing} image by reading and validating your definition file, then creating a `Containerfile`, and finally passing the `Containerfile` to Podman, which then packages and creates your {ExecEnvNameSing} container image. 
+After you install {Builder}, you can create a definition file that defines what {Builder} uses to create your {ExecEnvNameSing} image. 
+{Builder} makes an {ExecEnvNameSing} image by reading and validating your definition file, then creating a `Containerfile`, and finally passing the `Containerfile` to Podman, which then packages and creates your {ExecEnvNameSing} container image. 
 The definition file that you create must be in `yaml` format and contain different sections. The default definition filename, if not provided, is `execution-environment.yml`. For more information on the parts of a definition file, see xref:assembly-definition-file-breakdown[Breakdown of definition file content].
 
 The following is an example of a version 3 definition file. Each definition file must specify the major version number of the {Builder} feature set it uses. If not specified, {Builder} defaults to version 1, making most new features and definition keywords unavailable.

downstream/modules/builder/con-container_file.adoc

@@ -2,10 +2,16 @@
 
 = Containerfile
 
-After your definition file is created, {Builder} reads and validates it, creates a `Containerfile` and container build context, and optionally passes these to Podman to build your {ExecEnvNameSing} image. The container build occurs in several distinct stages: `base` , `galaxy`, `builder`, and `final`. The image build steps (along with any corresponding custom `prepend_` and `append_` steps defined in `additional_build_steps`) are:
+After your definition file is created, {Builder} reads and validates it, creates a `Containerfile` and container build context, and optionally passes these to Podman to build your {ExecEnvNameSing} image. 
+The container build occurs in several distinct stages: `base` , `galaxy`, `builder`, and `final`. 
+The image build steps (along with any corresponding custom `prepend_` and `append_` steps defined in `additional_build_steps`) are:
 
-. During the `base` build stage, the specified base image is (optionally) customized with components required by other build stages, including Python, `pip`, `ansible-core`, and `ansible-runner`. The resulting image is then validated to ensure that the required components are available (as they may have already been present in the base image). Ephemeral copies of the resulting customized `base` image are used as the base for all other build stages.
-. During the `galaxy` build stage, collections specified by the definition file are downloaded and stored for later installation during the `final` build stage. Python and system dependencies declared by the collections, if any, are also collected for later analysis.
-. During the `builder` build stage, Python dependencies declared by collections are merged with those listed in the definition file. This final set of Python dependencies is downloaded and built as Python wheels and stored for later installation during the `final` build stage.
+. During the `base` build stage, the specified base image is (optionally) customized with components required by other build stages, including Python, `pip`, `ansible-core`, and `ansible-runner`. 
+The resulting image is then validated to ensure that the required components are available (as they may have already been present in the base image). 
+Ephemeral copies of the resulting customized `base` image are used as the base for all other build stages.
+. During the `galaxy` build stage, collections specified by the definition file are downloaded and stored for later installation during the `final` build stage. 
+Python and system dependencies declared by the collections, if any, are also collected for later analysis.
+. During the `builder` build stage, Python dependencies declared by collections are merged with those listed in the definition file. 
+This final set of Python dependencies is downloaded and built as Python wheels and stored for later installation during the `final` build stage.
 . During the `final` build stage, the previously-downloaded collections are installed, along with system packages and any previously-built Python packages that were declared as dependencies by the collections or listed in the definition file.
 //Note if a diagram with the Main step actions gets created, it should be included here. Check with @nitzmahone

downstream/modules/builder/con-galaxy-dependencies.adoc

@@ -1,13 +1,13 @@
 [id="con-galaxy-dependencies"]
 
-= Galaxy
+= {Galaxy} dependencies
 The `galaxy` entry points to a valid requirements file or includes inline content for the `ansible-galaxy collection install -r ...` command.
 
 The entry `requirements.yml` can be a relative path from the directory of the {ExecEnvNameSing} definition's folder, or an absolute path.
 
 The content might look like the following:
 
-.Galaxy entry
+.{Galaxy} entry
 [example]
 ====
 ----

downstream/modules/builder/con-optional-build-command-arguments.adoc

@@ -2,7 +2,7 @@
 
 = Optional build command arguments
 
-The `-t` flag will tag your {ExecEnvNameSing} image with a specific name. For example, the following command will build an image named `my_first_ee_image`:
+The `-t` flag tags your {ExecEnvNameSing} image with a specific name. For example, the following command builds an image named `my_first_ee_image`:
 
 ====
 ----

downstream/modules/builder/con-python-dependencies.adoc

@@ -1,10 +1,12 @@
 [id="con-python-dependencies"]
 
-= Python
+= Python dependencies
 
 The `python` entry in the definition file points to a valid requirements file or to an inline list of Python requirements in PEP508 format for the `pip install -r ...` command.
 
-The entry `requirements.txt` is a file that installs extra Python requirements on top of what the Collections already list as their Python dependencies. It may be listed as a relative path from the directory of the {ExecEnvNameSing} definition's folder, or an absolute path. The contents of a `requirements.txt` file should be formatted like the following example, similar to the standard output from a `pip freeze` command:
+The entry `requirements.txt` is a file that installs extra Python requirements on top of what the Collections already list as their Python dependencies. 
+It might be listed as a relative path from the directory of the {ExecEnvNameSing} definition's folder, or an absolute path. 
+The contents of a `requirements.txt` file should be formatted like the following example, similar to the standard output from a `pip freeze` command:
 
 .Python entry
 [example]

downstream/modules/builder/con-system-dependencies.adoc

@@ -1,8 +1,10 @@
 [id="con-system-dependencies"]
 
-= System
+= System dependencies
 
-The `system` entry in the definition points to a link:https://docs.opendev.org/opendev/bindep/latest/readme.html[bindep] requirements file or to an inline list of bindep entries, which install system-level dependencies that are outside of what the collections already include as their dependencies. It can be listed as a relative path from the directory of the {ExecEnvNameSing} definition's folder, or as an absolute path. At a minimum, the the collection(s) must specify necessary requirements for `[platform:rpm]`.
+The `system` entry in the definition points to a link:https://docs.opendev.org/opendev/bindep/latest/readme.html[bindep] requirements file or to an inline list of bindep entries, which install system-level dependencies that are outside of what the collections already include as their dependencies. 
+It can be listed as a relative path from the directory of the {ExecEnvNameSing} definition's folder, or as an absolute path. 
+At a minimum, the collection(s) must specify necessary requirements for `[platform:rpm]`.
 
 To demonstrate this, the following is an example `bindep.txt` file that adds the `libxml2` and `subversion` packages to a container:
 
@@ -15,4 +17,4 @@ subversion [platform:rpm]
 ----
 ====
 
-Entries from multiple collections are combined into a single file. This is processed by `bindep` and then passed to `dnf`. Only requirements with no profiles or no runtime requirements will be installed to the image.
+Entries from multiple collections are combined into a single file. This is processed by `bindep` and then passed to `dnf`. Only requirements with no profiles or no runtime requirements are installed to the image.

downstream/modules/builder/ref-build-args-base-image.adoc

@@ -5,16 +5,16 @@
 The `build_arg_defaults` section of the definition file is a dictionary whose keys can provide default values for arguments to {Builder}. The following table lists values that can be used in `build_arg_defaults`:
 
 [cols="a,a"]
-|===
+|====
 | Value | Description
 
 | `ANSIBLE_GALAXY_CLI_COLLECTION_OPTS`
 | Allows the user to pass arbitrary arguments to the ansible-galaxy CLI during the collection installation phase. For example, the –pre flag to enable the installation of pre-release collections, or -c to disable verification of the server's SSL certificate.
 
 | `ANSIBLE_GALAXY_CLI_ROLE_OPTS`
-| Allows the user to pass any flags, such as –no-deps, to the role installation.
+| Allows the user to pass any flags, such as `–no-deps`, to the role installation.
 
-|===
+|====
 
 The values given inside `build_arg_defaults` are hard-coded into the `Containerfile`, so these values persist if `podman build` is called manually.
 

downstream/modules/builder/ref-definition-file-images.adoc

@@ -2,9 +2,10 @@
 
 = Images
 
-The `images` section of the definition file identifies the base image. Verification of signed container images is supported with the `podman` container runtime.
+The `images` section of the definition file identifies the base image. 
+Verification of signed container images is supported with the `podman` container runtime.
 
-See the following table for a list of values that you can use in `images`:
+The following table shows a list of values that you can use in `images`:
 
 [cols="a,a"]
 |===
@@ -19,4 +20,7 @@ The default image is `registry.redhat.io/ansible-automation-platform-24/ee-minim
 
 |===
 
-NOTE: If the same variable is specified in the CLI `--build-arg` flag, the CLI value will take higher precedence.
+[NOTE]
+====
+If the same variable is specified in the CLI `--build-arg` flag, the CLI value takes higher precedence.
+====

downstream/modules/builder/ref-example-file-to-build-image.adoc

@@ -0,0 +1,31 @@
+[id="ref-example-file-to-build-image"]
+
+= Example YAML file to build an image 
+
+The ansible-builder build command takes an execution environment definition as an input. 
+It outputs the build context necessary for building an execution environment image, and then builds that image. 
+The image can be re-built with the build context elsewhere, and produces the same result. 
+By default, the builder searches for a file named `execution-environment.yml` in the current directory.
+The following example `execution-environment.yml` file can be used as a starting point:
+
+----
+---
+version: 3
+dependencies:
+  galaxy: requirements.yml
+The content of requirements.yml:
+---
+collections:
+  - name: awx.awx
+To build an execution environment using the preceding files and run the following command:
+ansible-builder build
+...
+STEP 7: COMMIT my-awx-ee
+--> 09c930f5f6a
+09c930f5f6ac329b7ddb321b144a029dbbfcc83bdfc77103968b7f6cdfc7bea2
+Complete! The build context can be found at: context
+----
+
+In addition to producing a ready-to-use container image, the build context is preserved. 
+This can be rebuilt at a different time or location with the tools of your choice, such as docker build or podman build.
+

downstream/modules/builder/ref-scenario-update-hub-ca-cert.adoc

@@ -14,7 +14,7 @@ Use this example to customize the default definition file to include a CA certif
 Customizing the CA certificate using `prepend_base` means that the resulting CA configuration appears in all other build stages and the final image, because all other build stages inherit from the base image.
 ====
 
------
+----
 additional_build_files:
   # copy the CA public key into the build context, we will copy and use it in the base image later
   - src: files/rootCA.crt
@@ -32,4 +32,4 @@ options:
 
 [galaxy]
 server_list = automation_hub
------
+----