RHIDP:3206: added attributes subs to the source block

[pabel-rh]

IMPORTANT: Do Not Merge - To be merged by Docs Team Only

Version(s): main, 1.4.x, 1.3.x
Issue: RHIDP-3206

[rhdh-bot]

Updated preview: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-879/ @ 01/27/25 16:34:50

[linfraze]

the code looks right, but if you know where to find a preview of an example of an attribute being rendered in a code block in one of these changed files, please drop a link in the PR so we can easily see what the output looks like.

/lgtm

[linfraze]

@pabel-rh reminder to cherry-pick only to 1.4 and 1.3 since earlier version are EOL.

[themr0c]

The addition of the subs="+attributes" statement is not necessary when the code block does not contain any attribute.

[openshift-ci]

New changes are detected. LGTM label has been removed.

[pabel-rh]

I had to commit again to fix a few merge conflicts.
@linfraze , here is a preview link for one example of the usage of attributes within the source code block:

https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-879/authorization/#proc-sending-requests-to-the-rbac-rest-api-by-using-curl_title-authorization

@themr0c, I had gone ahead with Nick's alternate approach which he mentioned in the comments section, as that way, it someone in the future does edit one of the source code blocks which currently does not have any attributes, it just makes it easier.

[nickboldt]

The missing piece here is as described in the JIRA:

add a grep check in the build.sh (and/or build-ccutil.sh) that will fail if any
[source]
blocks are found which do NOT declare the
subs="attributes+"
rendering instruction.

So while adding all the instuctions is half the battle, anyone who adds new code snippets may fall into the same rendering trap in future unless we ALSO implement something in the build.sh or build-ccutil.sh (or some new PR check) which will ensure ALL code blocks can render attributes (even if they don't contain any). @themr0c WDYT?

There are >500 source blocks in the repo:

grep -E -r "\[source.+\]" . | wc -l
516

There are 32 [source] blocks with no langauge or subs instructions ([source,yaml], [source,bash],[source,yaml,subs="+attributes,+quotes"]`, etc.

grep -E -r "\[source\]$" . 
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/authorization/ref-rbac-rest-api-endpoints.adoc:[source]
./modules/customizing-techdocs/proc-techdocs-generate-site.adoc:[source]
./modules/customizing-techdocs/proc-techdocs-generate-site.adoc:[source]
./modules/customizing-techdocs/proc-techdocs-generate-site.adoc:[source]
./artifacts/rhdh-plugins-reference/acr/acr-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/acr/acr-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/acr/acr-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/jfrog-artifactory/jfrog-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/jfrog-artifactory/jfrog-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/ocm/ocm-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/quay/quay-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/quay/quay-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/topology/topology-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/topology/topology-plugin-readme.adoc:[source]
./artifacts/rhdh-plugins-reference/topology/topology-plugin-readme.adoc:[source]

If we implement the above simple grep check, then any number of hits >=1 will result in the PR failing to build and we could then point the user at the line with the [source] block that doesn't define a language or any subs.