[RHACS] [Docs] [rhacs-docs-main] ROX-33164: Fixing DITA errors in cli/command-reference/roxctl-image.adoc

[agantony]

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Merge into:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

[openshift-ci-robot]

@agantony: This pull request references ROX-33164 which is a valid jira issue.

Details

In response to this:

Version(s):
4.9+

Issue:
https://redhat.atlassian.net/browse/ROX-33164

Link to docs preview:

SME review: NA

Additional information:

• Merge into:
  • rhacs-docs-4.10
  • rhacs-docs-4.9

Instructions 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 openshift-eng/jira-lifecycle-plugin repository.

[ocpdocs-previewbot]

🤖 Mon May 18 09:28:17 - Prow CI generated the docs preview:
https://111785--ocpdocs-pr.netlify.app
Complete list of updated preview URLs: artifacts/updated_preview_urls.txt

[openshift-ci]

@agantony: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions 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.

[agantony]

📋 PR Summary

Type: DITA Modular Refactoring for CLI Reference
Files Changed: 15 files (+312, -188)
Pattern: CLI Reference Assembly with Assembly-Level Options

This PR refactors roxctl-image.adoc to follow Red Hat modular documentation standards and resolve DITA conversion errors.

---

✅ What Was Done

Assembly Refactoring

• ✅ Extracted inline content (usage, available commands, options) into separate modules
• ✅ Added comprehensive assembly abstract mentioning SBOM functionality
• ✅ Established proper module hierarchy with correct leveloffset values
• ✅ NEW: Created assembly-level options section (--timeout flag)

Module Splitting

• ✅ roxctl image sbom: Split into CONCEPT + usage + options (3 modules)
• ✅ roxctl image scan: Split into CONCEPT + usage + options (3 modules)
• ✅ roxctl image check: Split into CONCEPT + usage + options (3 modules)

DITA Compliance

• ✅ Added [role="_abstract"] to all modules
• ✅ Converted parent modules from REFERENCE to CONCEPT
• ✅ Set proper content types (CONCEPT/REFERENCE)
• ✅ Updated shared module options-inherited-from-the-parent-command.adoc

Content Quality

• ✅ No content loss during refactoring
• ✅ Build check passed
• ✅ Vale linting completed
• ✅ Assembly abstract now mentions SBOM generation capability

---

📂 Module Hierarchy

roxctl-image.adoc (assembly)
├── roxctl-image-overview.adoc (+1)
├── roxctl-image-usage.adoc (+2)
├── roxctl-image-available-commands.adoc (+2)
├── roxctl-image-options.adoc (+2)  ← NEW: Assembly-level options
├── options-inherited-from-the-parent-command.adoc (+1)
├── roxctl-image-sbom.adoc (+1)
│   ├── roxctl-image-sbom-usage.adoc (+2)
│   └── roxctl-image-sbom-options.adoc (+2)
├── roxctl-image-scan.adoc (+1)
│   ├── roxctl-image-scan-usage.adoc (+2)
│   └── roxctl-image-scan-options.adoc (+2)
└── roxctl-image-check.adoc (+1)
    ├── roxctl-image-check-usage.adoc (+2)
    └── roxctl-image-check-options.adoc (+2)

---

🧪 Review Guide

Main Assembly

📄 Preview: https://111785--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-image.html

Check:

• Assembly abstract appears with comprehensive description including SBOM
• Table of contents renders correctly
• All sections in proper hierarchy
• Usage syntax visible
• Available commands table present (3 commands)
• NEW: Assembly-level options section (--timeout flag)
• Inherited options section appears

Command Sections

roxctl image sbom

Location: Scroll to "roxctl image sbom" heading in the preview

Verify:

• Command description (abstract) with SBOM explanation (SPDX 2.3)
• Permission requirement mentioned (write permissions for Image resource)
• Usage section with syntax example
• Options table with all flags:
  • --format (json, csv, table, sarif)
  • --image (image name)
  • --output-format
  • --sbom-format (spdx)
  • Additional scan options

Modules:

• roxctl-image-sbom.adoc (CONCEPT)
• roxctl-image-sbom-usage.adoc (REFERENCE)
• roxctl-image-sbom-options.adoc (REFERENCE)

roxctl image scan

Location: Scroll to "roxctl image scan" heading

Verify:

• Command description with scan purpose
• Usage section
• Options table with key flags:
  • --cluster (cluster context)
  • --force (bypass cache)
  • --image (image name)
  • --include-snoozed
  • --json-fail-on-policy-violations
  • --output-format (json, csv, table, sarif)
  • --retry-timeout

Modules:

• roxctl-image-scan.adoc (CONCEPT)
• roxctl-image-scan-usage.adoc (REFERENCE)
• roxctl-image-scan-options.adoc (REFERENCE)

roxctl image check

Location: Scroll to "roxctl image check" heading

Verify:

• Command description with build-time policy violations purpose
• Usage section
• Options table with key flags:
  • --categories (policy categories)
  • --cluster (cluster context)
  • --compact-output
  • --force (bypass cache)
  • --headers
  • --image
  • --include-snoozed
  • --json
  • --json-fail-on-policy-violations
  • --output-format

Modules:

• roxctl-image-check.adoc (CONCEPT)
• roxctl-image-check-usage.adoc (REFERENCE)
• roxctl-image-check-options.adoc (REFERENCE)

Assembly-level Options (NEW)

Location: Scroll to "Options" heading (before "Options inherited from the parent command")

Verify:

• Section appears between "Available commands" and "Options inherited from the parent command"
• Options table with 1 flag: --timeout (applies to all subcommands)
• Proper placement in document hierarchy

Module:

• roxctl-image-options.adoc (REFERENCE) - NEW module

Note: This is a new section that didn't exist before - the timeout option was previously inline in the assembly.

---

📊 Stats

Metric	Count
Files modified	15
New modules created	11
Parent modules updated	3
Shared modules updated	1
Assembly updated	1
Lines added	+312
Lines removed	-188
Net change	+124

---

🆕 Key Differences from Other PRs

This PR includes assembly-level options (the --timeout flag that applies to all subcommands), which the other roxctl refactoring PRs did not have. This creates an additional "Options" section at the assembly level.

Option placement:

1. Available commands table
2. Assembly-level options (NEW: --timeout)
3. Options inherited from parent command
4. Command-specific sections with their own options

---

🔗 Related PRs

This PR follows the same modular refactoring pattern as:

• #111737 - roxctl-declarative-config
• #111782 - roxctl-netpol

All implement Red Hat modular documentation standards for CLI reference assemblies with DITA compliance.

---

✅ Ready for Review

This PR is ready for review and merge. All content has been preserved, DITA compliance achieved, and build checks passed.

Special attention: Please verify the new assembly-level options section appears in the correct location between "Available commands" and "Options inherited from the parent command".

---

[jlprevatt]

LGTM

[agantony]

/cherrypick rhacs-docs-4.11

[agantony]

/cherrypick rhacs-docs-4.10

[agantony]

/cherrypick rhacs-docs-4.9

[openshift-cherrypick-robot]

@agantony: new pull request created: #113797

Details

In response to this:

/cherrypick rhacs-docs-4.11

Instructions 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-cherrypick-robot]

@agantony: new pull request created: #113798

Details

In response to this:

/cherrypick rhacs-docs-4.10

Instructions 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-cherrypick-robot]

@agantony: new pull request created: #113799

Details

In response to this:

/cherrypick rhacs-docs-4.9

Instructions 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.