Fix AsciiDocDITA.ConceptLink warnings in virt documentation#111736
Closed
abrennan89 wants to merge 4 commits into
Closed
Fix AsciiDocDITA.ConceptLink warnings in virt documentation#111736abrennan89 wants to merge 4 commits into
abrennan89 wants to merge 4 commits into
Conversation
openshift-ci
Bot
added
the
needs-rebase
|
PR needs rebase. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
openshift-ci
Bot
added
the
size/XL
abrennan89
force-pushed
the
virt-concept-link-fixes-2026
branch
from
9449ee7 to
2ad6afb
Compare
Moved links and cross-references from main content to Additional resources
sections in assembly files to fix AsciiDocDITA.ConceptLink warnings.
Changes:
- Moved external links to Additional resources sections in assemblies
- Moved internal cross-references to Additional resources sections in assemblies
- Replaced inline links with quoted text in main content
- Added or updated Additional resources sections with proper attributes
- Added [role="_additional-resources"] and [id="additional-resources_{context}"]
attributes where missing
Files modified: 23 assembly files
- Includes about_virt, backup_restore, creating_vm, managing_vms,
post_installation_configuration, and support directories
Module files were not modified per OpenShift documentation standards.
Additional resources sections should only appear in assembly files.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
abrennan89
force-pushed
the
virt-concept-link-fixes-2026
branch
from
2ad6afb to
94efc26
Compare
openshift-ci
Bot
added
size/L
abrennan89
commented
May 15, 2026
Contributor
Author
abrennan89
left a comment
abrennan89
left a comment
There was a problem hiding this comment.
comments for Claude
Comment on lines
+18
to
+19
| * link:https://access.redhat.com/articles/6994974[{VirtProductName} - Tuning & Scaling Guide] | ||
| * link:https://access.redhat.com/articles/6994974[{VirtProductName} - Tuning & Scaling Guide] |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| * link:https://access.redhat.com/articles/6994974[{VirtProductName} - Tuning & Scaling Guide] | |
| * link:https://access.redhat.com/articles/6994974[{VirtProductName} - Tuning & Scaling Guide] | |
| * link:https://access.redhat.com/articles/6994974[{VirtProductName} - Tuning & Scaling Guide] |
Remove and do not add duplicate links
| @@ -17,7 +17,7 @@ Red Hat supports using {VirtProductName} 4.14 or later with {oadp-short} 1.3.x o | |||
| ==== | |||
|
|
|||
| ifndef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[] | |||
| Back up and restore virtual machines by using the xref:../../backup_and_restore/index.adoc#application-backup-restore-operations-overview[{oadp-full}]. | |||
| Back up and restore virtual machines by using the "{oadp-full}". | |||
Contributor
Author
There was a problem hiding this comment.
Suggested change
| Back up and restore virtual machines by using the "{oadp-full}". | |
| Back up and restore virtual machines by using the {oadp-full}. |
Only add quotation marks if the sentence is something like, "For more information, see "{oadp-full}". " or "See "{oadp-full}" " Don't add them if the link is just part of a regular sentence e.g. "by using the {oadp-full}"
|
|
||
| [id="prerequisites_virt-managing-vms-openshift-pipelines"] | ||
| == Prerequisites | ||
|
|
||
| * You have access to an {product-title} cluster with `cluster-admin` permissions. | ||
| * You have installed the OpenShift CLI (`oc`). | ||
| * You have link:https://docs.openshift.com/pipelines/latest/install_config/installing-pipelines.html[installed {pipelines-shortname}]. | ||
| * You have "installed {pipelines-shortname}". |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| * You have "installed {pipelines-shortname}". | |
| * You have installed {pipelines-shortname}. |
Comment on lines
+23
to
+25
| == Additional resources | ||
|
|
||
| * xref:../../virt/managing_vms/virt-exporting-vms.adoc#virt-exporting-vms[export virtual machines] |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| == Additional resources | |
| * xref:../../virt/managing_vms/virt-exporting-vms.adoc#virt-exporting-vms[export virtual machines] | |
| == Additional resources | |
| * xref:../../virt/managing_vms/virt-exporting-vms.adoc#virt-exporting-vms[export virtual machines] |
No space between title and links / bullet list
| @@ -17,9 +17,9 @@ endif::openshift-enterprise[] | |||
|
|
|||
| * The hostpath provisioner is a local storage provisioner designed for {VirtProductName}. If you want to configure local storage for virtual machines, you must enable the hostpath provisioner first. | |||
|
|
|||
| * xref:../../virt/post_installation_configuration/virt-node-placement-virt-components.adoc#virt-node-placement-virt-components[Node placement rules for {VirtProductName} Operators, workloads, and controllers] | |||
| * "Node placement rules for {VirtProductName} Operators, workloads, and controllers" | |||
Contributor
Author
There was a problem hiding this comment.
Suggested change
| * "Node placement rules for {VirtProductName} Operators, workloads, and controllers" | |
| * Node placement rules for {VirtProductName} Operators, workloads, and controllers |
| @@ -7,7 +7,7 @@ include::_attributes/common-attributes.adoc[] | |||
| toc::[] | |||
|
|
|||
| [role="_abstract"] | |||
| When you submit a support case to Red{nbsp}Hat Support, it is helpful to provide debugging information for {product-title} and {VirtProductName} by using the following tools: | |||
| When you submit a "support case" to Red{nbsp}Hat Support, it is helpful to provide debugging information for {product-title} and {VirtProductName} by using the following tools: | |||
Contributor
Author
There was a problem hiding this comment.
Suggested change
| When you submit a "support case" to Red{nbsp}Hat Support, it is helpful to provide debugging information for {product-title} and {VirtProductName} by using the following tools: | |
| When you submit a support case to Red{nbsp}Hat Support, it is helpful to provide debugging information for {product-title} and {VirtProductName} by using the following tools: |
- Remove duplicate link to Tuning & Scaling Guide - Remove unnecessary quotation marks from inline text - Fix spacing in Additional resources section Fixes based on review feedback from abrennan89.
Contributor
Author
|
✅ All review comments addressed:
Changes pushed in commit ef416a8. |
Applied fix-concept-links skill v3 to modules and snippets: - Removed xrefs and links from 38 module/snippet files - Applied proper text formatting (quotation mark rules) - Did NOT add Additional resources sections to modules/snippets - Links removed with context-aware quotation marks: - Explicit references (see, refer to, etc.): use quotes - Inline usage: no quotes Examples of changes: - 'The Operator is installed' (inline, no quotes) - 'see the "Disaster Recovery Guide"' (explicit ref, quotes) Files modified: 38 modules/snippets - modules/migrating-to-virt.adoc - modules/virt-cloud-platforms.adoc - modules/virt-about-dr-methods.adoc - And 35 more module/snippet files This completes the ConceptLink warning fixes across all file types.
abrennan89
commented
May 15, 2026
Contributor
Author
abrennan89
left a comment
abrennan89
left a comment
There was a problem hiding this comment.
comments for claude
|
|
||
| ifndef::openshift-dedicated[] | ||
| For a list of known storage providers for {VirtProductName}, see the link:https://catalog.redhat.com/search?searchType=software&badges_and_features=OpenShift+Virtualization&subcategories=Storage[ Red Hat Ecosystem Catalog]. | ||
| For a list of known storage providers for {VirtProductName}, see the " Red Hat Ecosystem Catalog". |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| For a list of known storage providers for {VirtProductName}, see the " Red Hat Ecosystem Catalog". | |
| For a list of known storage providers for {VirtProductName}, see the Red Hat Ecosystem Catalog. |
| [NOTE] | ||
| ==== | ||
| When running {VirtProductName} on {ibm-z-name} using OSA, RoCE, or HiperSockets interfaces, you must register the MAC address of the device. For more information, see link:https://www.ibm.com/docs/en/linux-on-systems?topic=choices-osa-interface-traffic-forwarding[OSA interface traffic forwarding] (IBM documentation). | ||
| When running {VirtProductName} on {ibm-z-name} using OSA, RoCE, or HiperSockets interfaces, you must register the MAC address of the device. For more information, see "OSA interface traffic forwarding" (IBM documentation). |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| When running {VirtProductName} on {ibm-z-name} using OSA, RoCE, or HiperSockets interfaces, you must register the MAC address of the device. For more information, see "OSA interface traffic forwarding" (IBM documentation). | |
| When running {VirtProductName} on {ibm-z-name} using OSA, RoCE, or HiperSockets interfaces, you must register the MAC address of the device. For more information, see "OSA interface traffic forwarding" in the IBM documentation. |
| CPU requirements for {VirtProductName}:: | ||
|
|
||
| * Must be supported by {op-system-base-full} 9. See link:https://catalog.redhat.com[Red Hat Ecosystem Catalog] for supported CPUs. | ||
| * Must be supported by {op-system-base-full} 9. See "Red Hat Ecosystem Catalog" for supported CPUs. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| * Must be supported by {op-system-base-full} 9. See "Red Hat Ecosystem Catalog" for supported CPUs. | |
| * Must be supported by {op-system-base-full} 9. See Red Hat Ecosystem Catalog for supported CPUs. |
| @@ -1,74 +1,66 @@ | |||
| // Module included in the following assemblies: | |||
Contributor
Author
There was a problem hiding this comment.
undo any updates to this file
|
|
||
| . Configure SSL VPN access to {ibm-cloud-title}: | ||
| .. Perform the procedure at link:https://cloud.ibm.com/docs/iaas-vpn?topic=iaas-vpn-getting-started[Getting started with {ibm-cloud-title} Virtual Private Networking] in the {ibm-cloud-title} documentation. | ||
| .. Perform the procedure at Getting started with {ibm-cloud-title} Virtual Private Networking in the {ibm-cloud-title} documentation. |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| .. Perform the procedure at Getting started with {ibm-cloud-title} Virtual Private Networking in the {ibm-cloud-title} documentation. | |
| .. Perform the procedure at "Getting started with {ibm-cloud-title} Virtual Private Networking" in the {ibm-cloud-title} documentation. |
Comment on lines
17
to
+18
| == Additional resources | ||
| [id="additional-resources_{virt-customize-web-console}"] |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| == Additional resources | |
| [id="additional-resources_{virt-customize-web-console}"] | |
| [id="additional-resources_{context}"] | |
| == Additional resources |
|
|
||
| include::modules/virt-enable-bulk-operations-web-console.adoc[leveloffset=+1] | ||
|
|
||
| include::modules/virt-create-custom-console-tabs.adoc[leveloffset=+1] | ||
|
|
||
| [role="_additional-resources"] | ||
| == Additional resources | ||
| [id="additional-resources_{virt-customize-web-console}"] | ||
| * xref:../../web_console/dynamic-plugin/overview-dynamic-plugin.adoc#overview-dynamic-plugin[dynamic plugins] |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| * xref:../../web_console/dynamic-plugin/overview-dynamic-plugin.adoc#overview-dynamic-plugin[dynamic plugins] | |
| * xref:../../web_console/dynamic-plugin/overview-dynamic-plugin.adoc#overview-dynamic-plugin[Dynamic plugins] |
| @@ -11,14 +11,20 @@ Export a virtual machine (VM) and its associated disks to import it into another | |||
|
|
|||
| You create a `VirtualMachineExport` custom resource (CR) by using the command-line interface. | |||
|
|
|||
| Alternatively, you can use the xref:../../virt/getting_started/virt-using-the-cli-tools.adoc#vm-export-commands_virt-using-the-cli-tools[`virtctl vmexport` command] to create a `VirtualMachineExport` CR and to download exported volumes. | |||
| Alternatively, you can use the "`virtctl vmexport` command" to create a `VirtualMachineExport` CR and to download exported volumes. | |||
Contributor
Author
There was a problem hiding this comment.
Suggested change
| Alternatively, you can use the "`virtctl vmexport` command" to create a `VirtualMachineExport` CR and to download exported volumes. | |
| Alternatively, you can use the `virtctl vmexport` command to create a `VirtualMachineExport` CR and to download exported volumes. |
|
|
||
| [NOTE] | ||
| ==== | ||
| You can migrate virtual machines between OpenShift Virtualization clusters by using the link:https://access.redhat.com/products/migration-toolkits-virtualization[Migration Toolkit for Virtualization]. | ||
| You can migrate virtual machines between OpenShift Virtualization clusters by using the "Migration Toolkit for Virtualization". |
Contributor
Author
There was a problem hiding this comment.
Suggested change
| You can migrate virtual machines between OpenShift Virtualization clusters by using the "Migration Toolkit for Virtualization". | |
| You can migrate virtual machines between OpenShift Virtualization clusters by using the Migration Toolkit for Virtualization. |
| @@ -32,9 +32,17 @@ ifdef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[] | |||
| ** Enabling the creation of load balancer services by using the {product-title} web console | |||
| endif::openshift-rosa,openshift-dedicated,openshift-rosa-hcp[] | |||
|
|
|||
| * xref:../../virt/post_installation_configuration/virt-post-install-storage-config.adoc#virt-post-install-storage-config[Storage configuration]: | |||
| * "Storage configuration": | |||
Contributor
Author
There was a problem hiding this comment.
Suggested change
| * "Storage configuration": | |
| * Storage configuration: |
Contributor
Author
Update: Modules and Snippets Now ProcessedAdded commit 9647f55 that processes module and snippet files to remove ConceptLink warnings. What Changed:38 module/snippet files now have xrefs/links properly removed: ✅ Correct Processing:
Examples:Module with inline usage (no quotes): - The {mtv-full} Operator link:https://...#installing-the-operator[is installed].
+ The {mtv-full} Operator is installed.Module with explicit reference (uses quotes): - For an overview, see the link:https://...disaster-recovery-guide[guide] in the Knowledgebase.
+ For an overview, see the "Red Hat {VirtProductName} disaster recovery guide" in the Knowledgebase.Module table with inline usage (no quotes): - | link:https://docs.aws.amazon.com/rosa/...[What is {product-rosa}?] in the AWS documentation
+ | What is {product-rosa}? in the AWS documentationSummary:
This completes the ConceptLink warning fixes across all file types in the virt directory. |
abrennan89
commented
May 15, 2026
Contributor
Author
abrennan89
left a comment
abrennan89
left a comment
There was a problem hiding this comment.
comments for claude
Fixed quotation mark usage based on reviewer feedback: PATTERN LEARNED: - Specific document TITLES get quotes: "Getting started with X", "OSA interface..." - Generic references NO quotes: "the documentation", "the catalog", "Microsoft documentation" - Product/feature names inline NO quotes: Compliance Operator, NIST-certified tool - Format: "in the X documentation" NOT "(X documentation)" Changes: MODULES (13 files): - Remove quotes from generic references (catalog, documentation) - Add quotes to specific document titles - Change "(X documentation)" to "in the X documentation" - Revert virt-fusion-access-san-release-updates.adoc (fixed in separate PR) SNIPPETS (2 files): - Remove Additional resources sections from butane-version.adoc - Remove Additional resources sections from technology-preview.adoc - Links belong in parent assemblies, not snippets ASSEMBLIES (3 files): - Remove quotes from inline product/feature names - Keep quotes only for specific document titles - OVN-Kubernetes (product) vs "Certified OpenShift CNI Plug-ins" (document) All review comments addressed.
|
@abrennan89: The following tests failed, say
Full PR test history. Your PR dashboard. DetailsInstructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here. |
Contributor
Author
All PR Review Comments Addressed ✅Commit ecb1aa0 addresses all remaining review comments. Key Pattern Learned:Quotation marks should only be used for specific document/article TITLES, not generic references or inline product names.
Format Rule:
Changes Made (15 files):Modules (11 files):
Snippets (2 files):
Assemblies (3 files):
All 30 review comments have been addressed! |
This was referenced May 15, 2026
Contributor
Author
|
This PR has been split into smaller, subdirectory-focused PRs for easier review: virt/about_virt
virt/backup_restore
virt/creating_vm
virt/creating_vms_advanced
virt/getting_started
virt/install
virt/managing_vms
virt/monitoring
virt/post_installation_configuration
virt/support
virt/updating
virt/vm_networking
snippets
Closing this PR in favor of the split PRs above. |
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixed AsciiDocDITA.ConceptLink warnings across virt documentation by moving links and cross-references from main content to Additional resources sections (assemblies only) and properly formatting text in modules/snippets.
Changes Made
Assembly Files (23 files)
[role="_additional-resources"]and[id="additional-resources_{context}"]attributes where missingModule and Snippet Files (38 files)
Files Modified: 61 Total
Assembly files span across key virt subdirectories:
about_virt/- About and architecture documentationbackup_restore/- Backup and restore procedurescreating_vm/- VM creation workflowsmanaging_vms/andmanaging_vms/advanced_vm_management/- VM management proceduresmanaging_vms/virtual_disks/- Virtual disk managementpost_installation_configuration/- Post-install configurationsupport/- Support and troubleshootingModule files span across all virt subdirectories, including install, live_migration, monitoring, nodes, storage, updating, and vm_networking.
Documentation Standards Applied
Quotation Mark Rules (Applied to ALL Files)
see "Document Name",For more information, see "Section Title"by using the {tool},You have installed the OperatorExamples from this PR:
see the "Red Hat OpenShift Virtualization disaster recovery guide"✅ (explicit reference)The {mtv-full} Operator is installed.✅ (inline usage, no quotes){VirtProductName} on {gcp-full}: Known issues and limitations in the Red Hat Knowledgebase✅ (inline)Additional Resources Formatting
== Additional resourcesheading and first bullet[role="_additional-resources"]and[id="additional-resources_{context}"]attributesFile Type Handling
Testing
🤖 Generated with Claude Code