Generate checluster references tables

[tolusha]

Signed-off-by: Anatolii Bazko abazko@redhat.com

Read our Contribution guide before submitting a PR.

What does this PR do?

Add scripts to sync doc and checluster crd

What issues does this PR fix or reference?

https://issues.redhat.com/browse/RHDEVDOCS-2216

PR Checklist

As the author of this Pull Request I made sure that:

• vale has been run successfully against the PR branch
• Link checker has been run successfully against the PR branch
• Documentation describes a scenario that is already covered by QE tests, otherwise an issue has been created and acknowledged by Che QE team
• Changed article references are updated where they are used (or a redirect has been set up on the docs side):
  • Dashboard branding.json
  • Chectl constants.ts

[MichalMaler]

LGTM. We are waiting for @l0rd approval now.

[tolusha]

gen script requires yq installed since it will be run on Jenkins

[MichalMaler]

gen script requires yq installed since it will be run on Jenkins

We can add:

.Prerequisites

• The yq tool is available. See link:https://pypi.org/project/yq/[yq homepage].

[themr0c]

The che-docs container has yq inside.

[themr0c]

Can you confirm it runs on che.openshift.io?

[tolusha]

I've just checked:

1. Created a workspace from the devfile [1]
2. Run yq command in che-docs containers.
   yes, it exists there.

[1] https://raw.githubusercontent.com/eclipse/che-docs/master/devfile.yaml

[themr0c]

@MichalMaler the requirement is to build the docs, not to the user-facing docs.

[themr0c]

Can you fix the shellcheck errors:

shellcheck tools/checluster_docs_gen.sh

In tools/checluster_docs_gen.sh line 17:
TABLE_HEADER="$NEWLINE[cols="2,5", options="header"]$NEWLINE:=== $NEWLINE Property: Description $NEWLINE"
^-- SC1087: Use braces when expanding arrays, e.g. ${array[idx]} (or ${var}[.. to quiet).
^----^ SC2140: Word is of the form "A"B"C" (B indicated). Did you mean "ABC" or "A"B"C"?

In tools/checluster_docs_gen.sh line 19:
PARENT_PATH=$( cd "$(dirname "${BASH_SOURCE[0]}")/.." ; pwd -P )
^-- SC2164: Use 'cd ... || exit' or 'cd ... || return' in case cd fails.

Did you mean:
PARENT_PATH=$( cd "$(dirname "${BASH_SOURCE[0]}")/.." || exit ; pwd -P )

In tools/checluster_docs_gen.sh line 27:
if [ $? -ne 0 ]; then
^-- SC2181: Check exit code directly with e.g. 'if mycmd;', not indirectly with $?.

In tools/checluster_docs_gen.sh line 41:
if [ $? -ne 0 ]; then
^-- SC2181: Check exit code directly with e.g. 'if mycmd;', not indirectly with $?.

In tools/checluster_docs_gen.sh line 59:
if [ $? -ne 0 ]; then
^-- SC2181: Check exit code directly with e.g. 'if mycmd;', not indirectly with $?.

In tools/checluster_docs_gen.sh line 88:
local section=$(echo "$RAW_CONTENT" | yq -M '.spec.validation.openAPIV3Schema.properties.status')
^-----^ SC2155: Declare and assign separately to avoid masking return values.

In tools/checluster_docs_gen.sh line 90:
local section=$(echo "$RAW_CONTENT" | yq -M '.spec.validation.openAPIV3Schema.properties.spec.properties.'$sectionName)
^-----^ SC2155: Declare and assign separately to avoid masking return values.
^----------^ SC2086: Double quote to prevent globbing and word splitting.

Did you mean:
local section=$(echo "$RAW_CONTENT" | yq -M '.spec.validation.openAPIV3Schema.properties.spec.properties.'"$sectionName")

In tools/checluster_docs_gen.sh line 94:
$(echo "$section" | yq -M '.properties | keys[]' )
^-- SC2207: Prefer mapfile or read -a to split command output (or quote to avoid splitting).

In tools/checluster_docs_gen.sh line 103:
description=$(echo "$section" | yq -M '.properties.'$prop'.description')
^---^ SC2086: Double quote to prevent globbing and word splitting.

Did you mean:
description=$(echo "$section" | yq -M '.properties.'"$prop"'.description')

For more information:
https://www.shellcheck.net/wiki/SC1087 -- Use braces when expanding arrays,...
https://www.shellcheck.net/wiki/SC2140 -- Word is of the form "A"B"C" (B in...
https://www.shellcheck.net/wiki/SC2155 -- Declare and assign separately to ...

[tolusha]

@themr0c
Sorry, to be honest I don't think that they are relevant. Where did they come from ?

[l0rd]

@themr0c
Sorry, to be honest I don't think that they are relevant. Where did they come from ?

@tolusha shellcheck is the most widespread linter for bash scripts (22K stars) and it's common to run our scripts against it.

[tolusha]

@themr0c
Fixed

[MichalMaler]

@themr0c Fabrice, I think we are good to go here :)
Good job @tolusha and thank you, @themr0c for setting up the linter.

[tolusha]

$ shellcheck checluster_docs_gen.sh 
$ 

no issues with spellchecker anymore ...

[themr0c]

So now, what can we do for the vale errors?

[MichalMaler]

let me take a look

[themr0c]

To fix vale errors:

For the static file, ref_checluster-custom-resource-fields-reference.adoc, this is straightforward: fix all vale errors in place.

For the generated file:

• Long term: fix the upstream of the file.
• Short term: substitutions, as we do with environment_docs_gen.sh

[tolusha]

Too much of vale errors, that's not possible to fix at script using substitution.
I suggest the following:

1. Fix build error and merge.
2. Doc team reviews CRD file to fix descriptions there.
3. Regenerate the doc with a new CRD

[tolusha]

I've just updated PR based on the latest changes from master branch of che-operator to see if we have any vale errors.

[tolusha]

I've update checluster doc based on master che-operator branch. So, we don't have value errors anymore.
But jenkins still fails.

[tolusha]

NB: If PR is merged then checluster references tables will be regenerated based on 7.25 version of che-operator (from antora-playbook.yaml) which doesn't contain all vale fixes.