fix: rework modular docs in PR #2139

.vale/styles/IBM/README-proselint.md

@@ -1,3 +1,4 @@
+<!-- vale off -->
 Copyright © 2014–2015, Jordan Suchow, Michael Pacer, and Lara A. Ross
 All rights reserved.
 

.vale/styles/IBM/README-write-good.md

@@ -1,3 +1,4 @@
+<!-- vale off -->
 Based on [write-good](https://github.com/btford/write-good).
 
 > Naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too.

.vale/styles/IBM/README.md

@@ -1,4 +1,5 @@
-IBM styleguide was created by the IBM : https://www.ibm.com/developerworks/library/styleguidelines/index.html
-All rights for the styleguide belong to IBM. 
+<!-- vale off -->
+IBM style guide was created by IBM: https://www.ibm.com/developerworks/library/styleguidelines/index.html
+All rights for the style guide belong to IBM. 
 
 Rules were compiled at: https://github.com/errata-ai/IBM

CONTRIBUTING.adoc

@@ -122,6 +122,8 @@ To build the Eclipse Che documentation from a Che workspace, follow the steps be
 
 .Procedure
 
+pass:[<!-- vale IBM.Slash = NO -->]
+
 . To build the documentation and start the preview server: open _My Workspace / User Runtimes / che-docs / Start preview server_.
 
 . To navigate to the preview, open _Preview_.
@@ -143,7 +145,6 @@ To build the Eclipse Che documentation from a Che workspace, follow the steps be
 .. The tool `+test-adoc+` tests the file and produces some output.
 
 
-
 [id="creating-a-new-topic-using-che"]
 == Creating a new topic using Che
 
@@ -180,6 +181,7 @@ Eclipse Che4z, OpenShift Connector.
 
 . The file is generated in the `+src/main/pages-che-7/<guide_name>/+` directory and the script displays related information.
 
+pass:[<!-- vale IBM.Slash = YES -->]
 
 == Adding images
 

Jenkinsfile

@@ -86,7 +86,7 @@ spec:
   options {
     buildDiscarder(logRotator(numToKeepStr: '5'))
     checkoutToSubdirectory('che-docs')
-    disableConcurrentBuilds()
+    disableConcurrentBuilds(abortPrevious: true)
     timeout(time: 15, unit: 'MINUTES')
   }
 

antora-playbook-for-publication.yml

@@ -11,8 +11,8 @@ site:
 content:
   sources:
     - url: ./
-      branches: "7.38.x"
-      edit_url: "https://github.com/eclipse/che-docs/edit/7.38.x/{path}"
+      branches: "7.39.x"
+      edit_url: "https://github.com/eclipse/che-docs/edit/7.39.x/{path}"
 output:
   destinations:
     - provider: fs

antora.yml

@@ -31,7 +31,7 @@ asciidoc:
     identity-provider-id: keycloak
     identity-provider-image-url: quay.io/eclipse/che-keycloak
     identity-provider-url: https://www.keycloak.org/
-    identity-provider-version: "6.0"
+    identity-provider-version: "15.0"
     identity-provider: Keycloak
     image-puller-cr-name: KubernetesImagePuller
     image-puller-deployment-id: kubernetes-image-puller-operator
@@ -55,9 +55,9 @@ asciidoc:
     link-cli-github: https://github.com/che-incubator/chectl
     link-identity-provider-documentation-openshift-3: https://www.keycloak.org/docs/latest/server_admin/#openshift-3
     link-identity-provider-documentation-openshift-4: https://www.keycloak.org/docs/latest/server_admin/#openshift-4
-    link-identity-provider-github: "https://www.keycloak.org/docs/6.0//server_admin/#github"
-    link-identity-provider-oidc: "https://www.keycloak.org/docs/6.0/server_admin/#_oidc"
-    link-identity-provider-saml: "https://www.keycloak.org/docs/6.0/server_admin/#saml-v2-0-identity-providers"
+    link-identity-provider-github: "https://www.keycloak.org/docs/15.0//server_admin/#github"
+    link-identity-provider-oidc: "https://www.keycloak.org/docs/15.0/server_admin/#_oidc"
+    link-identity-provider-saml: "https://www.keycloak.org/docs/15.0/server_admin/#saml-v2-0-identity-providers"
     link-installing-an-instance: xref:installation-guide:installing-che.adoc[]
     link-postgres-dockerfile-location: https://github.com/eclipse-che/che-server/tree/main/dockerfiles/postgres
     link-server-identity-provider-dockerfile-location: https://github.com/eclipse-che/che-server/tree/main/dockerfiles/keycloak
@@ -91,13 +91,13 @@ asciidoc:
     prod-operator-image-name: che-operator
     prod-operator: che-operator
     prod-prev-ver-major: "6"
-    prod-prev-ver: "7.37"
+    prod-prev-ver: "7.38"
     prod-short: Che
     prod-upstream: Eclipse{nbsp}Che
     prod-url: https://che-host:che-port
     prod-ver-major: "7"
-    prod-ver-patch: "7.38.1"
-    prod-ver: "7.38"
+    prod-ver-patch: "7.39.0"
+    prod-ver: "7.39"
     prod-workspace: che-ws
     prod: Eclipse Che
     prod2: Eclipse Che

modules/administration-guide/nav.adoc

@@ -34,7 +34,13 @@
 
 * xref:migration-from-postgresql-9-to-postgresql-13.adoc[]
 
-* xref:enabling-readiness-init-containers.adoc[]
+* xref:readiness-init-containers.adoc[]
+** xref:enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[]
+*** xref:enabling-readiness-init-containers-for-the-operator-installer.adoc[]
+*** xref:disabling-readiness-init-containers-for-the-operator-installer.adoc[]
+** xref:enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[]
+*** xref:enabling-readiness-init-containers-for-the-olm-installer.adoc[]
+*** xref:disabling-readiness-init-containers-for-the-olm-installer.adoc[]
 
 * xref:caching-images-for-faster-workspace-start.adoc[]
 ** xref:defining-the-list-of-images-to-pull.adoc[]

modules/administration-guide/pages/disabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,6 @@
+[id="disabling-readiness-init-containers-for-the-olm-installer"]
+:navtitle: Disabling the readiness init containers for the OLM installer
+:keywords: disable-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, olm
+:page-aliases: .:disabling-readiness-init-containers-for-the-olm-installer
+
+include::partial$proc_disabling-readiness-init-containers-for-the-olm-installer.adoc[]

modules/administration-guide/pages/disabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,6 @@
+[id="disabling-readiness-init-containers-for-the-operator-installer"]
+:navtitle: Disabling the readiness init containers for the Operator installer
+:keywords: disable-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, operator
+:page-aliases: .:disabling-readiness-init-containers-for-the-operator-installer
+
+include::partial$proc_disabling-readiness-init-containers-for-the-operator-installer.adoc[]

modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,6 @@
+[id="enabling-and-disabling-readiness-init-containers-for-the-olm-installer"]
+:navtitle: Enabling and disabling the readiness init containers for the OLM installer
+:keywords: enable-readiness-init-containers, disable-readiness-init-containers, enabling-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, olm
+:page-aliases: .:enabling-and-disabling-readiness-init-containers-for-the-olm-installer
+
+include::partial$assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[]

modules/administration-guide/pages/enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,6 @@
+[id="enabling-and-disabling-readiness-init-containers-for-the-operator-installer"]
+:navtitle: Enabling and disabling the readiness init containers for the Operator installer
+:keywords: enable-readiness-init-containers, disable-readiness-init-containers, enabling-readiness-init-containers, disabling-readiness-init-containers, init-container, readiness-init-container, startup, operator
+:page-aliases: .:enabling-and-disabling-readiness-init-containers-for-the-operator-installer
+
+include::partial$assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[]

modules/administration-guide/pages/enabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,6 @@
+[id="enabling-readiness-init-containers-for-the-olm-installer"]
+:navtitle: Enabling the readiness init containers for the OLM installer
+:keywords: enable-readiness-init-containers, enabling-readiness-init-containers, init-container, readiness-init-container, startup, olm
+:page-aliases: .:enabling-readiness-init-containers-for-the-olm-installer
+
+include::partial$proc_enabling-readiness-init-containers-for-the-olm-installer.adoc[]

modules/administration-guide/pages/enabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,6 @@
+[id="enabling-readiness-init-containers-for-the-operator-installer"]
+:navtitle: Enabling the readiness init containers for the Operator installer
+:keywords: enable-readiness-init-containers, enabling-readiness-init-containers, init-container, readiness-init-container, startup, operator
+:page-aliases: .:enabling-readiness-init-containers-for-the-operator-installer
+
+include::partial$proc_enabling-readiness-init-containers-for-the-operator-installer.adoc[]

modules/administration-guide/pages/managing-backups-using-cli.adoc

@@ -2,6 +2,6 @@
 // = Managing backups through cli
 :navtitle: Managing backups using CLI
 :keywords: administration-guide, backup, recovery
-:page-aliases: .:managing-backups-through-cli
+:page-aliases: .:managing-backups-through-cli, managing-backups-using-chectl
 
 include::partial$proc_managing-backups-through-cli.adoc[]

modules/administration-guide/pages/readiness-init-containers.adoc

@@ -0,0 +1,6 @@
+[id="readiness-init-containers"]
+:navtitle: Readiness init containers
+:keywords: init-container, readiness-init-container, startup
+:page-aliases: .:readiness-init-containers
+
+include::partial$assembly_readiness-init-containers.adoc[]

modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc

@@ -0,0 +1,13 @@
+:parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-olm-installer: {context}
+
+[id="enabling-and-disabling-readiness-init-containers-for-the-olm-installer_{context}"]
+= Enabling and disabling the readiness init containers for the OLM installer
+
+:context: enabling-and-disabling-readiness-init-containers-for-the-olm-installer
+
+You can enable and disable the readiness init containers for {prod-short} installed by the OLM installer, which is a {prod-short} installer that uses the Operator Lifecycle Manager:
+
+* xref:enabling-readiness-init-containers-for-the-olm-installer.adoc[Enabling the readiness init containers for the OLM installer]
+* xref:disabling-readiness-init-containers-for-the-olm-installer.adoc[Disabling the readiness init containers for the OLM installer]
+
+:context: {parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-olm-installer}

modules/administration-guide/partials/assembly_enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc

@@ -0,0 +1,13 @@
+:parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-operator-installer: {context}
+
+[id="enabling-and-disabling-readiness-init-containers-for-the-operator-installer_{context}"]
+= Enabling and disabling the readiness init containers for the Operator installer
+
+:context: enabling-and-disabling-readiness-init-containers-for-the-operator-installer
+
+You can enable and disable the readiness init containers for {prod-short} installed by the Operator installer:
+
+* xref:enabling-readiness-init-containers-for-the-operator-installer.adoc[Enabling the readiness init containers for the Operator installer]
+* xref:disabling-readiness-init-containers-for-the-operator-installer.adoc[Disabling the readiness init containers for the Operator installer]
+
+:context: {parent-context-of-enabling-and-disabling-readiness-init-containers-for-the-operator-installer}

modules/administration-guide/partials/assembly_readiness-init-containers.adoc

@@ -0,0 +1,16 @@
+:parent-context-of-readiness-init-containers: {context}
+
+[id="readiness-init-containers_{context}"]
+= Readiness init containers
+
+:context: readiness-init-containers
+
+{prod-short} Operator installs {prod-short} and starts its containers in the correct order. If a node with {prod-short} is restarted and all {prod-short} containers start simultaneously, some containers may fail because some other component they depend on is not ready. To avoid such failures, the readiness init containers queue the containers for {prod-short} components to start in the correct order.
+
+The readiness init containers are disabled by default. If you choose to enable them, proceed according to the installation method used to install {prod-short}:
+
+* xref:enabling-and-disabling-readiness-init-containers-for-the-operator-installer.adoc[]
+
+* xref:enabling-and-disabling-readiness-init-containers-for-the-olm-installer.adoc[]
+
+:context: {parent-context-of-readiness-init-containers}

modules/administration-guide/partials/con_a-workspace-example.adoc

@@ -9,9 +9,6 @@ The following devfile defines the {prod-short} workspace:
 
 include::example$snip_a-{project-context}-workspace-example.adoc[]
 
-pass:[<!-- vale Vale.Spelling = NO -->]
-
-pass:[<!-- vale Vale.Terms = NO -->]
 
 This table provides the memory requirements for each workspace component:
 
@@ -24,22 +21,22 @@ This table provides the memory requirements for each workspace component:
 |Default memory request
 
 |Workspace
-|theia-ide (default `cheEditor`)
+|`theia-ide` (default `cheEditor`)
 |512 MiB
 |512 MiB
 
 |Workspace
-|machine-exec (default `chePlugin`)
+|`machine-exec` (default `chePlugin`)
 |128 MiB
 |32 MiB
 
 |Workspace
-|vscode-typescript (`chePlugin`)
+|`vscode-typescript` (`chePlugin`)
 |512 MiB
 |512 MiB
 
 |Workspace
-|nodejs (`dockerimage`)
+|`nodejs` (`dockerimage`)
 |1 GiB
 |512 MiB
 
@@ -53,15 +50,12 @@ This table provides the memory requirements for each workspace component:
 >s|1.38 GiB
 |===
 
-pass:[<!-- vale Vale.Spelling = YES -->]
-
-pass:[<!-- vale Vale.Terms = YES -->]
 
 * The `theia-ide` and `machine-exec` components are implicitly added to the workspace, even when not included in the devfile.
 * The resources required by `machine-exec` are the default for `chePlugin`.
 * The resources for `theia-ide` are specifically set in the `cheEditor` `meta.yaml` to *512 MiB* as `memoryLimit`.
 * The Typescript VS Code extension has also overridden the default memory limits. In its `meta.yaml` file, the limits are explicitly specified to *512 MiB*.
-* {prod-short} is applying the defaults for the dockerimage component type: a memory limit of *1 GiB* and a memory request of *512 MiB*.
+* {prod-short} is applying the defaults for the `dockerimage` component type: a memory limit of *1 GiB* and a memory request of *512 MiB*.
 * The JWT container requires *128 MiB* of memory.
 
 Adding all together results in *1.38 GiB* of memory requests with a *2.25 GiB* limit.

modules/administration-guide/partials/con_define-backup-server-for-operator.adoc

@@ -37,7 +37,7 @@ spec:
 ----
 
 <1> Optional property that specifies the protocol to be used. The default value is `https` with `http` as the second allowed option.
-<2> Backup server hostname.
+<2> Backup server host name.
 <3> Optional property that specifies the port on which the backup server is running. The default value is `8000`.
 <4> Path on the backup server where the backup snapshots are stored.
 <5> Secret name containing a repository password, stored in the `repo-password` field. If the secret contains only one field, its name is arbitrary. The password is used to encrypt and decrypt backup snapshots data.
@@ -64,7 +64,7 @@ spec:
 ----
 
 <1> Optional property that specifies the protocol to be used. The default value is `https` with `http` as the second allowed option.
-<2> Optional property that specifies the S3 hostname. The default value is `s3.amazonaws.com`.
+<2> Optional property that specifies the S3 host name. The default value is `s3.amazonaws.com`.
 <3> Optional property that specifies the port on which the backup server is running.
 <4> The name of the bucket resource where the backup snapshots are stored. The bucket resource must be manually pre-created.
 <5> The name of the secret containing a repository password, stored in the `repo-password` field. If the secret contains only one field, this name is arbitrary. The password is used to encrypt and decrypt backup snapshots data.
@@ -91,7 +91,7 @@ spec:
 ----
 
 <1> User name on the remote server to login with using the SSH protocol.
-<2> Remote server hostname.
+<2> Remote server host name.
 <3> Optional property that specifies the port on which an SFTP server is running. The default value is `22`.
 <4> Absolute or relative path on the server where backup snapshots are stored.
 <5> The name of the secret containing a repository password, stored in the `repo-password` field. If the secret contains only one field, this name is arbitrary. The password is used to encrypt and decrypt backup snapshots data.

modules/administration-guide/partials/con_super-privileged-mode.adoc

@@ -10,7 +10,7 @@ The *super-privileged* mode is disabled by default. To change to the *super-priv
 [options="header"]
 |====
 |Path|HTTP Method|Description
-|/workspace/namespace/{namespace:.*}|GET|Get all workspaces for the given {orch-namespace}.
-|/workspace/\{id}|DELETE|Stop a workspace.
-|/workspace/\{key:.*}|GET|Get a workspace by key.
+|`/workspace/namespace/{namespace:.*}`|GET|Get all workspaces for the given {orch-namespace}.
+|`/workspace/\{id}`|DELETE|Stop a workspace.
+|`/workspace/\{key:.*}`|GET|Get a workspace by key.
 |====

modules/administration-guide/partials/proc_configuring-che-to-work-with-external-PostgreSQL.adoc

@@ -62,7 +62,7 @@ spec:
   auth:
     identityProviderPostgresSecret: <identity-database-credentials> <5>
 ----
-<1> External database hostname
+<1> External database host name
 <2> External database port
 <3> Secret name with {prod-short} server database credentials
 <4> {prod-short} server database name

modules/administration-guide/partials/proc_configuring-gitlab-servers.adoc

@@ -2,7 +2,7 @@
 [id="configuring_gitlab_servers_{context}"]
 = Configuring GitLab servers
 
-To use a GitLab server as a project sources supplier, register the GitLab server URL with {prod-short} using the `CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS` property and specify the hostname of the server to register.
+To use a GitLab server as a project sources supplier, register the GitLab server URL with {prod-short} using the `CHE_INTEGRATION_GITLAB_SERVER__ENDPOINTS` property and specify the host name of the server to register.
 
 .Example
 ----