[RHIDP-12787]: Add local SonarCloud lint script and fix remaining CQA errors (#1950)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: themr0c

.claude/skills/cqa-05-modular-elements-checklist.md

@@ -134,6 +134,27 @@ Work through each checkbox in the checklist for thorough validation.
 | **PROCEDURE with custom blocks** | `.Installation steps` | Use `.Procedure` |
 | **CONCEPT with numbered steps** | 1. Do this<br>2. Do that | Move to PROCEDURE module |
 
+### Fixing non-standard block titles
+
+Non-standard block titles (`.Example XYZ`, `.Sample config`, `.Available props`, etc.) are the most common CQA-05 violation. The fix depends on context:
+
+1. **If surrounding text already describes the block** → just delete the `.Title` line entirely. The preceding paragraph provides sufficient context.
+2. **If no surrounding context exists** → convert the block title to a lead-in sentence before the block (without the dot prefix). For example, `.Example creating many PVCs` becomes `For example, to create many PVCs:`.
+3. **Never replace one non-standard title with another** (e.g., don't change `.Helm config excerpt` to `.Example`—`.Example` is also non-standard).
+4. **The script may only report the first violation per file.** Always scan the entire file for ALL `.Title` lines and fix them all.
+
+### Creating assemblies for inline content
+
+When a title `master.adoc` contains `== Section` headings with `leveloffset=+2` includes, extract them into proper nested assemblies:
+
+1. Create the assembly in `assemblies/<category>_<title>/assembly-<section-name>.adoc`
+2. **Use relative include paths**: `include::../modules/shared/...` (relative to the assembly directory), NOT `include::modules/shared/...` (relative to repo root)
+3. Add context save/restore boilerplate (`ifdef::context[:parent-context: {context}]` at top, restore at bottom)
+4. Change includes from `leveloffset=+2` to `leveloffset=+1` in the assembly
+5. In the title, replace the `==` section with `include::assemblies/.../assembly-....adoc[leveloffset=+1]`
+
+Similarly, if a title has inline content (paragraphs, lists) beyond the `[role="_abstract"]` introduction, extract it into a concept module.
+
 ## Validation Workflow
 
 1. **Run content type validation:**

.claude/skills/cqa-13-information-is-conveyed-using-the-correct-content.md

@@ -89,7 +89,7 @@ While RHDH documentation primarily uses Product documentation with modular struc
 - Validates PROCEDURE files have `.Procedure` section with steps
 - Validates CONCEPT files do not have `.Procedure` sections
 - Validates REFERENCE files do not have `.Procedure` sections
-- Validates ASSEMBLY files contain only intro + includes
+- Validates ASSEMBLY files have `include::` directives (no includes = wrong content type)
 - Checks filename prefix matches content type (proc-, con-, ref-, assembly-)
 
 **Target Results:**

.github/workflows/content-quality-assessment.yml

@@ -136,10 +136,8 @@ jobs:
             const cqaOutput = process.env.CQA_OUTPUT;
 
             let comment = '## Content Quality Assessment Results\n\n';
-            comment += '```\n';
             comment += cqaOutput;
-            comment += '\n```\n\n';
-            comment += '---\n';
+            comment += '\n\n---\n';
             comment += '*Automated CQA check run on the entire repository*\n';
 
             // Find existing CQA comment and update or create

.vscode/settings.json

@@ -23,6 +23,7 @@
         "pipelineruns",
         "podman",
         "preconfigured",
+        "previouscontext",
         "quicklinks",
         "redhat",
         "rhcr",
@@ -36,9 +37,14 @@
         "sysparam",
         "sysparm",
         "taskruns",
+        "techdocs",
         "tekton",
         "umoci",
         "virtualmachineinstances",
         "virtualmachines"
-    ]
+    ],
+    "sonarlint.connectedMode.project": {
+        "connectionId": "redhat-developer",
+        "projectKey": "redhat-developer_red-hat-developers-documentation-rhdh"
+    }
 }

assemblies/configure_customizing-rhdh/assembly-customize-rhdh-navigation.adoc

@@ -0,0 +1,31 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="customize-rhdh-navigation_{context}"]
+= Customize {product} navigation
+
+:previouscontext: {context}
+:context: customize-rhdh-navigation
+
+[role="_abstract"]
+You can customize navigation elements in {product}, including sidebar menu items, entity tab titles, and entity detail tab layouts.
+
+include::../modules/shared/con-sidebar-menu-items.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-customize-the-sidebar-menu-items-for-your-rhdh-instance.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-enable-sidebar-menu-items-localization-in-rhdh.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-configure-a-dynamic-plugin-menu-item-for-your-rhdh-instance.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-modify-or-add-a-custom-menu-items-for-your-rhdh-instance.adoc[leveloffset=+2]
+
+include::../modules/shared/proc-configure-entity-tab-titles.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-configure-entity-detail-tab-layout.adoc[leveloffset=+1]
+
+:context: {previouscontext}
+:!previouscontext:
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

…/assembly-customize-rhdh-appearance.adoc …y-customize-rhdh-theme-and-branding.adocassemblies/configure_customizing-rhdh/assembly-customize-rhdh-appearance.adoc renamed to assemblies/configure_customizing-rhdh/assembly-customize-rhdh-theme-and-branding.adoc assemblies/configure_customizing-rhdh/assembly-customize-rhdh-appearance.adoc renamed to assemblies/configure_customizing-rhdh/assembly-customize-rhdh-theme-and-branding.adoc

@@ -1,11 +1,11 @@
 :_mod-docs-content-type: ASSEMBLY
 ifdef::context[:parent-context: {context}]
 
-[id="customize-rhdh-appearance_{context}"]
-= Customize {product} appearance
+[id="customize-rhdh-theme-and-branding_{context}"]
+= Customize {product} theme and branding
 
 :previouscontext: {context}
-:context: customize-rhdh-appearance
+:context: customize-rhdh-theme-and-branding
 
 [role="_abstract"]
 By modifying the visual aspects of the interface, organizations can align {product} with their branding guidelines and improve the overall user experience.
@@ -28,38 +28,16 @@ You can also customize some components from the {product-short} GUI, such as the
 
 include::../modules/shared/proc-switch-the-theme-mode-for-your-rhdh-instance.adoc[leveloffset=+1]
 
-
 include::../modules/shared/proc-customize-the-branding-logo-of-your-rhdh-instance.adoc[leveloffset=+1]
 
-
-include::../modules/shared/con-sidebar-menu-items.adoc[leveloffset=+1]
-
-include::../modules/shared/proc-customize-the-sidebar-menu-items-for-your-rhdh-instance.adoc[leveloffset=+2]
-
-include::../modules/shared/proc-enable-sidebar-menu-items-localization-in-rhdh.adoc[leveloffset=+2]
-
-include::../modules/shared/proc-configure-a-dynamic-plugin-menu-item-for-your-rhdh-instance.adoc[leveloffset=+2]
-
-include::../modules/shared/proc-modify-or-add-a-custom-menu-items-for-your-rhdh-instance.adoc[leveloffset=+2]
-
-include::../modules/shared/proc-configure-entity-tab-titles.adoc[leveloffset=+1]
-
-
-include::../modules/shared/proc-configure-entity-detail-tab-layout.adoc[leveloffset=+1]
-
-
 include::../modules/shared/proc-customize-the-theme-mode-color-palettes-for-your-rhdh-instance.adoc[leveloffset=+1]
 
-
 include::../modules/shared/proc-customize-the-page-theme-header-for-your-rhdh-instance.adoc[leveloffset=+1]
 
-
 include::../modules/shared/proc-customize-the-font-for-your-rhdh-instance.adoc[leveloffset=+1]
 
-
 include::../modules/shared/ref-default-rhdh-theme.adoc[leveloffset=+1]
 
-
 include::../modules/shared/ref-default-theme.adoc[leveloffset=+1]
 
 include::../modules/shared/proc-load-a-custom-rhdh-theme-by-using-a-dynamic-plugin.adoc[leveloffset=+1]

assemblies/extend_configuring-dynamic-plugins/assembly-configure-rhdh-events-module.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
 
 [id="configure-rhdh-events-module_{context}"]
 
@@ -11,3 +12,6 @@ You can enable real-time updates for GitHub entities by configuring the Events M
 include::{docdir}/artifacts/snip-technology-preview.adoc[]
 
 include::../modules/shared/proc-configure-the-github-events-module-plugin.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/extend_configuring-dynamic-plugins/assembly-configure-the-topology-plugin.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
 
 [id="configure-the-topology-plugin_{context}"]
 = Configure the Topology plugin
@@ -16,3 +17,6 @@ include::../modules/shared/proc-view-tekton-pipelineruns.adoc[leveloffset=+1]
 include::../modules/shared/proc-view-virtual-machines.adoc[leveloffset=+1]
 
 include::../modules/shared/proc-enable-the-source-code-editor.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/extend_configuring-dynamic-plugins/assembly-enable-and-configure-the-jfrog-plugin.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
 
 [id="enable-and-configure-the-jfrog-plugin_{context}"]
 = Enable and configure the JFrog plugin
@@ -10,3 +11,6 @@ Enable and configure the JFrog Artifactory plugin to display container images fr
 include::../modules/shared/proc-enable-the-jfrog-artifactory-plugin.adoc[leveloffset=+1]
 
 include::../modules/shared/proc-configure-the-jfrog-artifactory-plugin.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/extend_configuring-dynamic-plugins/assembly-enable-and-configure-the-keycloak-plugin.adoc

@@ -1,4 +1,5 @@
 :_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
 
 [id="enable-and-configure-the-keycloak-plugin_{context}"]
 = Enable and configure the Keycloak plugin
@@ -12,3 +13,6 @@ include::../modules/shared/proc-enable-the-keycloak-plugin.adoc[leveloffset=+1]
 include::../modules/shared/proc-configure-the-keycloak-plugin.adoc[leveloffset=+1]
 
 include::../modules/shared/ref-keycloak-plugin-metrics.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]