Browse Source

[DOCS] Remove unneeded `ifeval`s from install docs (#98952)

Problem: The current install docs contain several `ifeval` statements that hide commands and code snippets based on the branch's release state. These statements make the Asciidoc hard to read  and maintain. It also makes doc changes difficult to preview.

Solution: Remove `ifeval` statements that hide commands or code snippets. Leave in any `ifeval` statements used to add warnings.
James Rodewig 2 years ago
parent
commit
1301995a46

+ 1 - 4
docs/plugins/install_remove.asciidoc

@@ -4,12 +4,10 @@
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of the Elastic Stack has not yet been released.
+WARNING: Version {version} of the Elastic Stack has not yet been released.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 This plugin can be installed using the plugin manager:
 
 ["source","sh",subs="attributes,callouts"]
@@ -25,7 +23,6 @@ install>> from {plugin_url}/{plugin_name}/{plugin_name}-{version}.zip. To verify
 the `.zip` file, use the
 {plugin_url}/{plugin_name}/{plugin_name}-{version}.zip.sha512[SHA hash] or
 {plugin_url}/{plugin_name}/{plugin_name}-{version}.zip.asc[ASC key].
-endif::[]
 
 [discrete]
 [id="{plugin_name}-remove"]

+ 2 - 10
docs/reference/setup/install/deb.asciidoc

@@ -30,12 +30,10 @@ wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo gpg --dearm
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of Elasticsearch has not yet been released.
+WARNING: Version {version} of Elasticsearch has not yet been released.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 You may need to install the `apt-transport-https` package on Debian before proceeding:
 
 [source,sh]
@@ -52,8 +50,6 @@ ifeval::["{release-state}"=="released"]
 echo "deb [signed-by=/usr/share/keyrings/elasticsearch-keyring.gpg] https://artifacts.elastic.co/packages/{major-version}/apt stable main" | sudo tee /etc/apt/sources.list.d/elastic-{major-version}.list
 --------------------------------------------------
 
-endif::[]
-
 ifeval::["{release-state}"=="prerelease"]
 
 ["source","sh",subs="attributes,callouts"]
@@ -110,12 +106,10 @@ include::skip-set-kernel-parameters.asciidoc[]
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of Elasticsearch has not yet been released.
+WARNING: Version {version} of Elasticsearch has not yet been released.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 The Debian package for Elasticsearch v{version} can be downloaded from the website and installed as follows:
 
 ["source","sh",subs="attributes"]
@@ -128,8 +122,6 @@ sudo dpkg -i elasticsearch-{version}-amd64.deb
 <1> Compares the SHA of the downloaded Debian package and the published checksum, which should output
     `elasticsearch-{version}-amd64.deb: OK`.
 
-endif::[]
-
 // Set a `distro` attribute so we can reuse files containing anchors
 :distro: deb
 [id="deb-security-configuration"]

+ 4 - 24
docs/reference/setup/install/docker.asciidoc

@@ -33,15 +33,11 @@ Docker image is currently available for this version.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 [source,sh,subs="attributes"]
 ----
 docker pull {docker-repo}:{version}
 ----
 
-endif::[]
-
 [[docker-verify-signature]]
 ==== Optional: Verify the image signature
 
@@ -57,8 +53,6 @@ Docker image signature is currently available for this version.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 Install the appropriate https://docs.sigstore.dev/cosign/installation/[Cosign application]
 for your operating system.
 
@@ -83,8 +77,6 @@ The following checks were performed on each of these signatures:
   - The signatures were verified against the specified public key
 --------------------------------------------
 
-endif::[]
-
 
 [[docker-cli-run-dev-mode]]
 ==== Run {es} in Docker
@@ -123,7 +115,6 @@ Docker image is currently available for this version.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
 [source,sh,subs="attributes"]
 ----
 docker run --name es01 --net elastic -p 9200:9200 -it -m 1GB {docker-image}
@@ -132,8 +123,6 @@ docker run --name es01 --net elastic -p 9200:9200 -it -m 1GB {docker-image}
 TIP: Use the `-m` flag to set a memory limit for the container.
 
 The command prints the `elastic` user password and an enrollment token for {kib}.
-
-endif::[]
 --
 
 . Copy the generated `elastic` password and enrollment token. These credentials
@@ -193,13 +182,10 @@ Docker image is currently available for this version.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
 [source,sh,subs="attributes"]
 ----
 docker run -e ENROLLMENT_TOKEN="<token>" --name es02 --net elastic -it {docker-image}
 ----
-
-endif::[]
 --
 
 . Call the <<cat-nodes,cat nodes API>> to verify the node was added to the cluster.
@@ -265,15 +251,13 @@ repository on GitHub.
 
 --
 ifeval::["{release-state}"=="unreleased"]
-NOTE: Version {version} of {es} has not been released,
-so the sample Docker Compose and configuration files are not yet available for
-this version. See the {stack-gs-current}/get-started-docker.html[current version]
-for the latest sample files.
+WARNING: Version {version} of {es} has not been released,
+so the following Docker Compose and configuration files won't work.
+See the {stack-gs-current}/get-started-docker.html[current version]
+for the latest working files.
 endif::[]
 --
 
---
-ifeval::["{release-state}"!="unreleased"]
 
 [discrete]
 [[docker-env-file]]
@@ -315,8 +299,6 @@ then only be accessible from the host machine itself.
 include::docker/docker-compose.yml[]
 ----
 
-endif::[]
---
 
 ===== Start your cluster with security enabled and configured
 
@@ -687,7 +669,6 @@ instead. The command must:
 * Use the `elasticsearch-keystore` tool with the `create -p` option. You'll be
   prompted to enter a password for the keystore.
 
-ifeval::["{release-state}"!="unreleased"]
 For example:
 
 [source,sh,subs="attributes"]
@@ -711,7 +692,6 @@ bin/elasticsearch-keystore \
 add my.secure.setting \
 my.other.secure.setting
 ----
-endif::[]
 
 If you've already created the keystore and don't need to update it, you can
 bind-mount the `elasticsearch.keystore` file directly. You can use the

+ 2 - 10
docs/reference/setup/install/rpm.asciidoc

@@ -34,12 +34,10 @@ rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of Elasticsearch has not yet been released.
+WARNING: Version {version} of Elasticsearch has not yet been released.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 Create a file called `elasticsearch.repo` in the `/etc/yum.repos.d/` directory
 for RedHat based distributions, or in the `/etc/zypp/repos.d/` directory for
 OpenSuSE based distributions, containing:
@@ -58,8 +56,6 @@ autorefresh=1
 type=rpm-md
 --------------------------------------------------
 
-endif::[]
-
 ifeval::["{release-state}"=="prerelease"]
 
 ["source","sh",subs="attributes,callouts"]
@@ -101,12 +97,10 @@ endif::[]
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of Elasticsearch has not yet been released.
+WARNING: Version {version} of Elasticsearch has not yet been released.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 The RPM for Elasticsearch v{version} can be downloaded from the website and installed as follows:
 
 ["source","sh",subs="attributes"]
@@ -119,8 +113,6 @@ sudo rpm --install elasticsearch-{version}-x86_64.rpm
 <1> Compares the SHA of the downloaded RPM and the published checksum, which should output
     `elasticsearch-{version}-x86_64.rpm: OK`.
 
-endif::[]
-
 include::skip-set-kernel-parameters.asciidoc[]
 
 // Set a `distro` attribute so we can reuse files containing anchors

+ 2 - 10
docs/reference/setup/install/targz.asciidoc

@@ -19,12 +19,10 @@ see the <<jvm-version, JVM version requirements>>
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of {es} has not yet been released.
+WARNING: Version {version} of {es} has not yet been released.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 The Linux archive for {es} v{version} can be downloaded and installed as follows:
 
 ["source","sh",subs="attributes"]
@@ -39,19 +37,15 @@ cd elasticsearch-{version}/ <2>
     `elasticsearch-{version}-linux-x86_64.tar.gz: OK`.
 <2> This directory is known as `$ES_HOME`.
 
-endif::[]
-
 [[install-macos]]
 ==== Download and install archive for MacOS
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of {es} has not yet been released.
+WARNING: Version {version} of {es} has not yet been released.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 The MacOS archive for {es} v{version} can be downloaded and installed as follows:
 
 ["source","sh",subs="attributes"]
@@ -67,8 +61,6 @@ cd elasticsearch-{version}/ <2>
     `elasticsearch-{version}-darwin-x86_64.tar.gz: OK`.
 <2> This directory is known as `$ES_HOME`.
 
-endif::[]
-
 ifdef::include-xpack[]
 [role="xpack"]
 [[targz-enable-indices]]

+ 1 - 5
docs/reference/setup/install/zip-windows.asciidoc

@@ -29,12 +29,10 @@ see the <<jvm-version, JVM version requirements>>
 
 ifeval::["{release-state}"=="unreleased"]
 
-Version {version} of {es} has not yet been released.
+WARNING: Version {version} of {es} has not yet been released.
 
 endif::[]
 
-ifeval::["{release-state}"!="unreleased"]
-
 Download the `.zip` archive for {es} {version} from: https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-{version}-windows-x86_64.zip
 
 Unzip it with your favorite unzip tool. This will create a folder called
@@ -46,8 +44,6 @@ window, `cd` to the `%ES_HOME%` directory, for instance:
 cd C:\elasticsearch-{version}
 ----------------------------
 
-endif::[]
-
 ifdef::include-xpack[]
 [role="xpack"]
 [[windows-enable-indices]]

+ 2 - 6
docs/reference/setup/run-elasticsearch-locally.asciidoc

@@ -34,10 +34,9 @@ Desktop]. Go to **Preferences > Resources > Advanced** and set Memory to at leas
 . Start an Elasticsearch container:
 ifeval::["{release-state}"=="unreleased"]
 +
-NOTE: Version {version} of {es} has not yet been released, so no
+WARNING: Version {version} of {es} has not yet been released, so no
 Docker image is currently available for this version.
 endif::[]
-ifeval::["{release-state}"!="unreleased"]
 +
 [source,sh,subs="attributes"]
 ----
@@ -45,7 +44,6 @@ docker network create elastic
 docker pull docker.elastic.co/elasticsearch/elasticsearch:{version}
 docker run --name elasticsearch --net elastic -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" -t docker.elastic.co/elasticsearch/elasticsearch:{version}
 ----
-endif::[]
 +
 When you start Elasticsearch for the first time, the generated `elastic` user password and
 Kibana enrollment token are output to the terminal.
@@ -65,17 +63,15 @@ Kibana enables you to easily send requests to Elasticsearch and analyze, visuali
 . In a new terminal session, start Kibana and connect it to your Elasticsearch container:
 ifeval::["{release-state}"=="unreleased"]
 +
-NOTE: Version {version} of {kib} has not yet been released, so no
+WARNING: Version {version} of {kib} has not yet been released, so no
 Docker image is currently available for this version.
 endif::[]
-ifeval::["{release-state}"!="unreleased"]
 +
 [source,sh,subs="attributes"]
 ----
 docker pull docker.elastic.co/kibana/kibana:{version}
 docker run --name kibana --net elastic -p 5601:5601 docker.elastic.co/kibana/kibana:{version}
 ----
-endif::[]
 +
 When you start Kibana, a unique URL is output to your terminal.