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

[agantony]

Version(s):
4.9+

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

Link to docs preview:

SME review: NA

Additional information:

• Cherrypick to:
  • 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:

• Cherrypick to:
  • 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 Jul 20 12:52:03 - Prow CI generated the docs preview:

https://111791--ocpdocs-pr.netlify.app/openshift-acs/latest/cli/command-reference/roxctl-sensor.html

[agantony]

📋 PR Summary

Type: DITA Modular Refactoring for CLI Reference
Files Changed: 21 files (+388, -235)
Pattern: CLI Reference Assembly with 3-Level Hierarchy

This PR refactors roxctl-sensor.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 assembly abstract describing RHACS service deployment
• ✅ Established proper 3-level module hierarchy (assembly → command → subcommand)
• ✅ Created assembly-level options section (--retry-timeout, --timeout)

Module Splitting

• ✅ roxctl sensor generate: Split into CONCEPT + usage + options (3 modules)
  • ✅ roxctl sensor generate k8s: Split into CONCEPT + usage + options (3 modules at leveloffset +3)
  • ✅ roxctl sensor generate openshift: Split into CONCEPT + usage + options (3 modules at leveloffset +3)
• ✅ roxctl sensor get-bundle: Split into CONCEPT + usage + options (3 modules)
• ✅ roxctl sensor generate-certs: 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
• ✅ Parameter documentation in usage sections

---

📂 Module Hierarchy

roxctl-sensor.adoc (assembly)
├── roxctl-sensor-overview.adoc (+1)
├── roxctl-sensor-usage.adoc (+2)
├── roxctl-sensor-available-commands.adoc (+2)
├── roxctl-sensor-options.adoc (+2)  ← Assembly-level options
├── options-inherited-from-the-parent-command.adoc (+1)
├── roxctl-sensor-generate.adoc (+1)
│   ├── roxctl-sensor-generate-usage.adoc (+2)
│   ├── roxctl-sensor-generate-options.adoc (+2)
│   ├── roxctl-sensor-generate-k8s.adoc (+2)
│   │   ├── roxctl-sensor-generate-k8s-usage.adoc (+3)
│   │   └── roxctl-sensor-generate-k8s-options.adoc (+3)
│   └── roxctl-sensor-generate-openshift.adoc (+2)
│       ├── roxctl-sensor-generate-openshift-usage.adoc (+3)
│       └── roxctl-sensor-generate-openshift-options.adoc (+3)
├── roxctl-sensor-get-bundle.adoc (+1)
│   ├── roxctl-sensor-get-bundle-usage.adoc (+2)
│   └── roxctl-sensor-get-bundle-options.adoc (+2)
└── roxctl-sensor-generate-certs.adoc (+1)
    ├── roxctl-sensor-generate-certs-usage.adoc (+2)
    └── roxctl-sensor-generate-certs-options.adoc (+2)

---

🧪 Review Guide

Main Assembly

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

Check:

• Assembly abstract appears (deploying RHACS services)
• Table of contents renders correctly
• All sections in proper hierarchy
• Usage syntax visible
• Available commands table present (3 commands: generate, generate-certs, get-bundle)
• Assembly-level options section (2 timeout flags)
• Inherited options section appears

Command Sections

roxctl sensor generate (with subcommands)

Location: Scroll to "roxctl sensor generate" heading in the preview

Verify:

• Command description (generate deployment files)
• Usage section
• Options table with flags:
  • --admission-controller-listen-on-creates/events/updates
  • --collection-method (kernel-module, ebpf, no-collection)
  • --create-admission-controller
  • --create-upgrade-controller
  • --disable-audit-logs
  • --output-dir
  • --slim-collector
• Two subcommands documented

Modules:

• roxctl-sensor-generate.adoc (CONCEPT)
• roxctl-sensor-generate-usage.adoc (REFERENCE)
• roxctl-sensor-generate-options.adoc (REFERENCE)

roxctl sensor generate k8s (subcommand)

Location: Nested under "roxctl sensor generate" as H3 heading

Verify:

• Subcommand description (Kubernetes-specific)
• Usage section
• Options table:
  • --istio-version (Istio support versions)
• Proper nesting level (H3/H4, not H2)

Modules (leveloffset=+3):

• roxctl-sensor-generate-k8s.adoc (CONCEPT, +2)
• roxctl-sensor-generate-k8s-usage.adoc (REFERENCE, +3)
• roxctl-sensor-generate-k8s-options.adoc (REFERENCE, +3)

roxctl sensor generate openshift (subcommand)

Location: Nested under "roxctl sensor generate" as H3 heading

Verify:

• Subcommand description (OpenShift-specific)
• Usage section
• Options table:
  • --istio-version
  • --monitoring-endpoint
• Matches hierarchy of k8s subcommand

Modules (leveloffset=+3):

• roxctl-sensor-generate-openshift.adoc (CONCEPT, +2)
• roxctl-sensor-generate-openshift-usage.adoc (REFERENCE, +3)
• roxctl-sensor-generate-openshift-options.adoc (REFERENCE, +3)

roxctl sensor get-bundle

Location: Scroll to "roxctl sensor get-bundle" heading

Verify:

• Command description (download bundle)
• Usage section
• Options table with flags:
  • --admission-controller-listen-on-creates/events/updates
  • --collection-method
  • --output-dir
  • --remove
  • --slim-collector

Modules:

• roxctl-sensor-get-bundle.adoc (CONCEPT)
• roxctl-sensor-get-bundle-usage.adoc (REFERENCE)
• roxctl-sensor-get-bundle-options.adoc (REFERENCE)

roxctl sensor generate-certs

Location: Scroll to "roxctl sensor generate-certs" heading

Verify:

• Command description (certificate renewal)
• Usage section with parameter documentation:
  • <cluster_details> parameter explained
• Options table:
  • --output-dir

Modules:

• roxctl-sensor-generate-certs.adoc (CONCEPT)
• roxctl-sensor-generate-certs-usage.adoc (REFERENCE)
• roxctl-sensor-generate-certs-options.adoc (REFERENCE)

---

📊 Stats

Metric	Count
Files modified	21
New modules created	16
Parent modules updated	4
Shared modules updated	1
Assembly updated	1
Lines added	+388
Lines removed	-235
Net change	+153

---

🎯 Key Features

3-Level Hierarchy

This PR implements a 3-level command hierarchy:

• Level 1 (assembly): roxctl sensor
• Level 2 (commands): generate, get-bundle, generate-certs
• Level 3 (subcommands): generate k8s, generate openshift

The subcommands use leveloffset=+3 for their usage/options modules.

Assembly-Level Options

Includes assembly-level options that apply to all subcommands:

• --retry-timeout duration
• --timeout duration

Parameter Documentation

Usage modules include parameter descriptions:

• <cluster_details> parameter in generate-certs usage

---

🔗 Related PRs

This PR follows the same modular refactoring pattern as:

• #111737 - roxctl-declarative-config
• #111782 - roxctl-netpol (3-level hierarchy)
• #111785 - roxctl-image

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:

• Verify the 3-level hierarchy renders correctly (generate → k8s/openshift)
• Check that subcommands appear nested under their parent command
• Confirm assembly-level options appear in correct location

---

[jlprevatt]

LGTM except for the 2 comments; both of the comments are about stuff that might confuse users.

[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]

/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: #115793

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: #115794

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: #115795

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.