OTA - listing module headings in assembly comments

skopacz1 · skopacz1 · commit e998f7bae9e8 · 2023-08-15T12:16:34.000-04:00
diff --git a/updating/understanding_updates/how-updates-work.adoc b/updating/understanding_updates/how-updates-work.adoc
@@ -8,24 +8,29 @@ toc::[]
 
 The following sections describe each major aspect of the {product-title} (OCP) update process in detail. For a general overview of how updates work, see the xref:../../updating/understanding_updates/intro-to-updates.adoc#understanding-openshift-updates[Introduction to OpenShift updates].
 
+// Evaluation of update availability
 include::modules/update-evaluate-availability.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../updating/understanding_updates/understanding-update-channels-release.adoc#conditional-updates-overview_understanding-update-channels-releases[Update recommendation removals and Conditional Updates]
 
+// Release images
 include::modules/update-release-images.adoc[leveloffset=+1]
 
+// Update process workflow
 include::modules/update-process-workflow.adoc[leveloffset=+1]
 
+// Understanding how manifests are applied during an update
 include::modules/update-manifest-application.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../updating/understanding_updates/understanding-openshift-update-duration.adoc#understanding-openshift-update-duration[Understanding {product-title} update duration]
 
+// Understanding how the Machine Config Operator updates nodes
 include::modules/update-mco-process.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/updating/understanding_updates/intro-to-updates.adoc b/updating/understanding_updates/intro-to-updates.adoc
@@ -30,6 +30,7 @@ After the CVO updates the entire control plane through this process, the Machine
 
 ifdef::openshift-enterprise[]
 
+// Common questions about update availability
 include::modules/update-availability-faq.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -39,12 +40,16 @@ include::modules/update-availability-faq.adoc[leveloffset=+1]
 
 endif::openshift-enterprise[]
 
+// About the OpenShift Update Service
 include::modules/update-service-overview.adoc[leveloffset=+1]
 
+// Understanding cluster Operator condition types
 include::modules/determining-upgrade-viability-conditiontype.adoc[leveloffset=+1]
 
+// Understanding cluster version condition types
 include::modules/determining-upgrade-viability-cv-conditiontype.adoc[leveloffset=+1]
 
+// Common terms
 include::modules/update-common-terms.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/updating/understanding_updates/understanding-openshift-update-duration.adoc b/updating/understanding_updates/understanding-openshift-update-duration.adoc
@@ -18,6 +18,7 @@ To do: Remove this comment once 4.13 docs are EOL.
 == Prerequisites
 * You are familiar with xref:../../architecture/architecture.adoc#architecture[OpenShift Container Platform architecture] and xref:../../updating/understanding_updates/intro-to-updates.adoc#understanding-openshift-updates[OpenShift Container Platform updates].
 
+// Factors affecting update duration
 include::modules/update-duration-factors.adoc[leveloffset=+1]
 
 [id="cluster-update-phases"]
@@ -28,13 +29,15 @@ In {product-title}, the cluster update happens in two phases:
 * Machine Config Operator (MCO) node updates
 
 
+// Cluster Version Operator target update payload deployment
 include::modules/update-duration-cvo.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../updating/understanding_updates/intro-to-updates.adoc#understanding-openshift-updates[Introduction to OpenShift updates]
 
+// Machine Config Operator node updates
 include::modules/update-duration-mco.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
@@ -43,9 +46,11 @@ include::modules/update-duration-mco.adoc[leveloffset=+2]
 * xref:../../post_installation_configuration/machine-configuration-tasks.adoc#machine-config-overview-post-install-machine-configuration-tasks[Machine config overview]
 * xref:../../nodes/pods/nodes-pods-configuring.adoc#nodes-pods-configuring-pod-distruption-about_nodes-pods-configuring[Pod disruption budget]
 
+// Estimating cluster update time
 include::modules/update-duration-estimate-cluster-update-time.adoc[leveloffset=+1]
 
 ifndef::openshift-origin[]
+// {op-system-base-full} compute nodes
 include::modules/update-duration-rhel-nodes.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/updating/understanding_updates/understanding-update-channels-release.adoc b/updating/understanding_updates/understanding-update-channels-release.adoc
@@ -51,6 +51,7 @@ ifdef::openshift-origin[]
 
 endif::openshift-origin[]
 
+// Update channels
 include::modules/understanding-update-channels.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/updating/updating_a_cluster/eus-eus-update.adoc b/updating/updating_a_cluster/eus-eus-update.adoc
@@ -32,8 +32,10 @@ There are a number of caveats to consider when attempting an EUS-to-EUS update.
 
 * All the clusters might update using EUS channels for a conventional update without pools paused, but only clusters with non control-plane `MachineConfigPools` objects can do EUS-to-EUS update with pools paused.
 
+// EUS-to-EUS update
 include::modules/updating-eus-to-eus-upgrade.adoc[leveloffset=+1]
 
+// EUS-to-EUS update using the web console
 include::modules/updating-eus-to-eus-upgrade-console.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
@@ -45,6 +47,7 @@ include::modules/updating-eus-to-eus-upgrade-console.adoc[leveloffset=+2]
 * xref:../../operators/admin/olm-upgrading-operators.adoc#olm-upgrading-operators[Updating installed Operators]
 
 
+// EUS-to-EUS update using the CLI
 include::modules/updating-eus-to-eus-upgrade-cli.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
diff --git a/updating/updating_a_cluster/migrating-to-multi-payload.adoc b/updating/updating_a_cluster/migrating-to-multi-payload.adoc
@@ -21,6 +21,7 @@ For information about configuring your multi-architecture compute machines, see
 Migration from a multi-architecture payload to a single-architecture payload is not supported. Once a cluster has transitioned to using a multi-architecture payload, it can no longer accept a single-architecture update payload.
 ====
 
+// Migrating to a cluster with multi-architecture compute machines using the CLI
 include::modules/migrating-to-multi-arch-cli.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
diff --git a/updating/updating_a_cluster/update-using-custom-machine-config-pools.adoc b/updating/updating_a_cluster/update-using-custom-machine-config-pools.adoc
@@ -59,8 +59,13 @@ Also, you need to consider how much extra capacity you have available in your cl
 
 You can use this update process with all documented {product-title} update processes. However, the process does not work with {op-system-base-full} machines, which are updated using Ansible playbooks.
 
+// About performing a canary rollout update
 include::modules/update-using-custom-machine-config-pools-about.adoc[leveloffset=+1]
+
+// Creating machine config pools to perform a canary rollout update
 include::modules/update-using-custom-machine-config-pools-mcp.adoc[leveloffset=+1]
+
+// Pausing the machine config pools
 include::modules/update-using-custom-machine-config-pools-pause.adoc[leveloffset=+1]
 
 [id="update-using-custom-machine-config-pools-update_{context}"]
@@ -73,6 +78,8 @@ When the MCPs enter ready state, you can perform the cluster update. See one of
 
 After the update is complete, you can start to unpause the MCPs one-by-one.
 
+// Unpausing the machine config pools
 include::modules/update-using-custom-machine-config-pools-unpause.adoc[leveloffset=+1]
 
+// Moving a node to the original machine config pool
 include::modules/update-using-custom-machine-config-pools-mcp-remove.adoc[leveloffset=+1]
diff --git a/updating/updating_a_cluster/updating-cluster-cli.adoc b/updating/updating_a_cluster/updating-cluster-cli.adoc
@@ -42,15 +42,18 @@ See xref:../../authentication/using-rbac.adoc#using-rbac[Using RBAC to define an
 .Additional resources
 * xref:../../architecture/architecture-installation.adoc#unmanaged-operators_architecture-installation[Support policy for unmanaged Operators]
 
+// Pausing a MachineHealthCheck resource
 include::modules/machine-health-checks-pausing.adoc[leveloffset=+1]
 
+// About updating single node {product-title}
 include::modules/updating-sno.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
 .Additional resources
 
 * For information on which machine configuration changes require a reboot, see the note in xref:../../architecture/control-plane.adoc#about-machine-config-operator_control-plane[About the Machine Config Operator].
 
+// Updating a cluster by using the CLI
 include::modules/update-upgrading-cli.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
@@ -59,6 +62,7 @@ include::modules/update-upgrading-cli.adoc[leveloffset=+1]
 * xref:../../updating/updating_a_cluster/eus-eus-update.adoc#eus-eus-update[Performing an EUS-to-EUS update]
 * xref:../../updating/understanding_updates/understanding-update-channels-release.adoc#understanding-update-channels-releases[Understanding update channels and releases]
 
+// Updating along a conditional update path
 include::modules/update-conditional-updates.adoc[leveloffset=+1]
 
 // OKD removed the section that this link points to.
@@ -72,4 +76,5 @@ ifndef::openshift-origin[]
 
 endif::openshift-origin[]
 
+// Changing the update server by using the CLI
 include::modules/update-changing-update-server-cli.adoc[leveloffset=+1]
diff --git a/updating/updating_a_cluster/updating-cluster-rhel-compute.adoc b/updating/updating_a_cluster/updating-cluster-rhel-compute.adoc
@@ -31,6 +31,7 @@ See xref:../../authentication/using-rbac.adoc#using-rbac[Using RBAC to define an
 * xref:../../architecture/architecture-installation.adoc#unmanaged-operators_architecture-installation[Support policy for unmanaged Operators]
 
 
+// Updating a cluster by using the web console
 include::modules/update-upgrading-web.adoc[leveloffset=+1]
 
 [id="updating-cluster-rhel-compute-hooks"]
@@ -39,10 +40,14 @@ include::modules/update-upgrading-web.adoc[leveloffset=+1]
 You can use _hooks_ to run Ansible tasks on the RHEL compute machines during
 the {product-title} update.
 
+// About Ansible hooks for updates
 include::modules/rhel-compute-about-hooks.adoc[leveloffset=+2]
 
+// Configuring the Ansible inventory file to use hooks
 include::modules/rhel-compute-using-hooks.adoc[leveloffset=+2]
 
+// Available hooks for RHEL compute machines
 include::modules/rhel-compute-available-hooks.adoc[leveloffset=+2]
 
+// Updating {op-system-base} compute machines in your cluster
 include::modules/rhel-compute-updating.adoc[leveloffset=+1]
diff --git a/updating/updating_a_cluster/updating-hardware-on-nodes-running-on-vsphere.adoc b/updating/updating_a_cluster/updating-hardware-on-nodes-running-on-vsphere.adoc
@@ -33,13 +33,19 @@ To update the hardware of your virtual machines (VMs) on VMware vSphere, update
 As of {product-title} 4.13, VMware virtual hardware version 13 is no longer supported. You need to update to VMware version 15 or later for supporting functionality.
 ====
 
+// Updating the virtual hardware for control plane nodes on vSphere
 include::modules/update-vsphere-virtual-hardware-on-control-plane-nodes.adoc[leveloffset=+2]
+
+// Updating the virtual hardware for compute nodes on vSphere
 include::modules/update-vsphere-virtual-hardware-on-compute-nodes.adoc[leveloffset=+2]
+
+// Updating the virtual hardware for template on vSphere
 include::modules/update-vsphere-virtual-hardware-on-template.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../nodes/nodes/nodes-nodes-working.adoc#nodes-nodes-working-evacuating_nodes-nodes-working[Understanding how to evacuate pods on nodes]
 
+// Scheduling an update for virtual hardware on vSphere
 include::modules/scheduling-virtual-hardware-update-on-vsphere.adoc[leveloffset=+1]
diff --git a/updating/updating_a_cluster/updating-hosted-control-planes.adoc b/updating/updating_a_cluster/updating-hosted-control-planes.adoc
@@ -14,6 +14,11 @@ To do: Remove this comment once 4.13 docs are EOL.
 
 On hosted control planes for {product-title}, updates are decoupled between the control plane and the nodes. Your service cluster provider, which is the user that hosts the cluster control planes, can manage the updates as needed. The hosted cluster handles control plane updates, and node pools handle node updates.
 
+// Updates for hosted control planes
 include::modules/updates-for-hosted-control-planes.adoc[leveloffset=+1]
+
+// Updating node pools for hosted control planes
 include::modules/updating-node-pools-for-hcp.adoc[leveloffset=+1]
+
+// Configuring node pools for hosted control planes
 include::modules/configuring-node-pools-for-hcp.adoc[leveloffset=+1]
diff --git a/updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.adoc b/updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.adoc
@@ -28,6 +28,7 @@ The following steps outline the high-level workflow on how to update a cluster i
 
 . Perform a supported update procedure from the documentation as you would with a connected cluster.
 
+// Using the OpenShift Update Service in a disconnected environment
 include::modules/disconnected-osus-overview.adoc[leveloffset=+1]
 
 .Additional resources
@@ -68,6 +69,7 @@ data:
 <1> The OpenShift Update Service Operator requires the config map key name updateservice-registry in the registry CA cert.
 <2> If the registry has the port, such as `registry-with-port.example.com:5000`, `:` should be replaced with `..`.
 
+// Updating the global cluster pull secret
 include::modules/images-update-global-pull-secret.adoc[leveloffset=+1]
 
 [id="update-service-install"]
@@ -80,24 +82,29 @@ To install the OpenShift Update Service, you must first install the OpenShift Up
 For clusters that are installed in disconnected environments, also known as disconnected clusters, Operator Lifecycle Manager by default cannot access the Red Hat-provided OperatorHub sources hosted on remote registries because those remote sources require full internet connectivity. For more information, see xref:../../../operators/admin/olm-restricted-networks.adoc#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks].
 ====
 
+// Installing the OpenShift Update Service Operator by using the web console
 include::modules/update-service-install-web-console.adoc[leveloffset=+2]
 
+// Installing the OpenShift Update Service Operator by using the CLI
 include::modules/update-service-install-cli.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../../operators/user/olm-installing-operators-in-namespace.adoc#olm-installing-operators-in-namespace[Installing Operators in your namespace].
 
+// Creating the OpenShift Update Service graph data container image
 include::modules/update-service-graph-data.adoc[leveloffset=+1]
 
 [id="update-service-create-service"]
 == Creating an OpenShift Update Service application
 
 You can create an OpenShift Update Service application by using the {product-title} web console or CLI.
 
+// Creating an OpenShift Update Service application by using the web console
 include::modules/update-service-create-service-web-console.adoc[leveloffset=+2]
 
+// Creating an OpenShift Update Service application by using the CLI
 include::modules/update-service-create-service-cli.adoc[leveloffset=+2]
 
 [NOTE]
@@ -106,6 +113,7 @@ The policy engine route name must not be more than 63 characters based on RFC-11
 and must be no more than 63 characters`, try creating the Update Service with a shorter name.
 ====
 
+// Configuring the Cluster Version Operator (CVO)
 include::modules/update-service-configure-cvo.adoc[leveloffset=+3]
 
 [NOTE]
diff --git a/updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update.adoc b/updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update.adoc
@@ -36,16 +36,22 @@ See xref:../../../authentication/using-rbac.adoc#using-rbac[Using RBAC to define
 If you run an Operator or you have configured any application with the pod disruption budget, you might experience an interruption during the update process. If `minAvailable` is set to 1 in `PodDisruptionBudget`, the nodes are drained to apply pending machine configs which might block the eviction process. If several nodes are rebooted, all the pods might run on only one node, and the `PodDisruptionBudget` field can prevent the node drain.
 ====
 
+// Pausing a MachineHealthCheck resource
 include::modules/machine-health-checks-pausing.adoc[leveloffset=+1]
 
+// Retrieving a release image digest
 include::modules/update-restricted-image-digests.adoc[leveloffset=+1]
 
+// Updating the disconnected cluster
 include::modules/update-restricted.adoc[leveloffset=+1]
 
+// Configuring image registry repository mirroring
 include::modules/images-configuration-registry-mirror.adoc[leveloffset=+1]
 
+// Converting ImageContentSourcePolicy (ICSP) files for image registry repository mirroring
 include::modules/images-configuration-registry-mirror-convert.adoc[leveloffset=+2]
 
+// Widening the scope of the mirror image catalog to reduce the frequency of cluster node reboots
 include::modules/generating-icsp-object-scoped-to-a-registry.adoc[leveloffset=+1]
 
 [id="additional-resources_security-container-signature"]
diff --git a/updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc b/updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc
@@ -70,13 +70,15 @@ If you do not have an existing solution for a container image registry, the xref
 
 Before you perform the mirror procedure, you must prepare the host to retrieve content and push it to the remote location.
 
+// Installing the OpenShift CLI by downloading the binary
 include::modules/cli-installing-cli.adoc[leveloffset=+2]
 
 [role="_additional-resources"]
 .Additional resources
 
 * xref:../../../cli_reference/openshift_cli/extending-cli-plugins.adoc#cli-installing-plugins_cli-extend-plugins[Installing and using CLI plugins]
 
+// Configuring credentials that allow images to be mirrored
 include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+2]
 
 [id=mirroring-ocp-resources-ocmirror]
@@ -181,4 +183,5 @@ include::modules/oc-mirror-image-set-config-examples.adoc[leveloffset=+2]
 // Command reference for oc-mirror
 include::modules/oc-mirror-command-reference.adoc[leveloffset=+2]
 
+// Mirroring images using the oc adm release mirror command
 include::modules/update-mirror-repository.adoc[leveloffset=+1]
diff --git a/updating/updating_a_cluster/updating_disconnected_cluster/uninstalling-osus.adoc b/updating/updating_a_cluster/updating_disconnected_cluster/uninstalling-osus.adoc
@@ -19,15 +19,19 @@ To remove a local copy of the OpenShift Update Service (OSUS) from your cluster,
 
 You can delete an OpenShift Update Service application by using the {product-title} web console or CLI.
 
+// Deleting an OpenShift Update Service application by using the web console
 include::modules/update-service-delete-service-web-console.adoc[leveloffset=+2]
 
+// Deleting an OpenShift Update Service application by using the CLI
 include::modules/update-service-delete-service-cli.adoc[leveloffset=+2]
 
 [id="update-service-uninstall"]
 == Uninstalling the OpenShift Update Service Operator
 
 You can uninstall the OpenShift Update Service Operator by using the {product-title} web console or CLI.
 
+// Uninstalling the OpenShift Update Service Operator by using the web console
 include::modules/update-service-uninstall-web-console.adoc[leveloffset=+2]
 
+// Uninstalling the OpenShift Update Service Operator by using the CLI
 include::modules/update-service-uninstall-cli.adoc[leveloffset=+2]
