Issue #1358 Use links instead of xrefs in docs

This allows us to use modules in multiple assemblies while ensuring that the links in each module point to the correct assembly context. This will enable us to use some modules in the Release Notes assembly in addition to the Getting Started Guide (namely the system requirements).
crc-org · Jul 10, 2020 · 1904e3a · 1904e3a
1 parent 1674246
commit 1904e3a
Show file tree

Hide file tree

Showing 11 changed files with 22 additions and 17 deletions.
diff --git a/docs/source/meta/product-attributes.adoc b/docs/source/meta/product-attributes.adoc
@@ -24,8 +24,13 @@
 :rh-prod: {rh} {prod}
 :bin: crc
 
+// Documentation naming
+:crc-gsg: {rh-prod} Getting Started Guide
+
 // URLs
 :crc-download-url: https://cloud.redhat.com/openshift/install/crc/installer-provisioned
+:crc-gsg-url: https://code-ready.github.io/crc/
+
 :odo-docs-url: https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/understanding-odo.html
 :odo-docs-url-installing: https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/installing-odo.html
 :odo-docs-url-single-component: https://docs.openshift.com/container-platform/latest/cli_reference/openshift_developer_cli/creating-a-single-component-application-with-odo.html
diff --git a/docs/source/topics/proc_accessing-the-openshift-cluster-with-oc.adoc b/docs/source/topics/proc_accessing-the-openshift-cluster-with-oc.adoc
@@ -4,7 +4,7 @@
 .Prerequisites
 
 * A running {prod} virtual machine.
-For more information, see <<starting-the-virtual-machine_{context}>>.
+For more information, see link:{crc-gsg-url}#starting-the-virtual-machine_gsg[Starting the virtual machine].
 
 .Procedure
 
@@ -45,7 +45,7 @@ $ oc get co
 * {prod} disables the `machine-config` and `monitoring` Operators by default.
 ====
 
-See <<troubleshooting-codeready-containers_{context}>> if you cannot access the {prod} OpenShift cluster.
+See link:{crc-gsg-url}#troubleshooting-codeready-containers_gsg[Troubleshooting {prod}] if you cannot access the {prod} OpenShift cluster.
 
 .Additional resources
 

diff --git a/docs/source/topics/proc_accessing-the-openshift-web-console.adoc b/docs/source/topics/proc_accessing-the-openshift-web-console.adoc
@@ -4,7 +4,7 @@
 .Prerequisites
 
 * A running {prod} virtual machine.
-For more information, see <<starting-the-virtual-machine_{context}>>.
+For more information, see link:{crc-gsg-url}#starting-the-virtual-machine_gsg[Starting the virtual machine].
 
 .Procedure
 
@@ -23,7 +23,7 @@ Use the `developer` user for creating projects or OpenShift applications and for
 Only use the `kubeadmin` user for administrative tasks such as creating new users, setting roles, and so on.
 ====
 
-See <<troubleshooting-codeready-containers_{context}>> if you cannot access the {prod} OpenShift cluster.
+See link:{crc-gsg-url}#troubleshooting-codeready-containers_gsg[Troubleshooting {prod}] if you cannot access the {prod} OpenShift cluster.
 
 .Additional resources
 

diff --git a/docs/source/topics/proc_deploying-sample-application-with-odo.adoc b/docs/source/topics/proc_deploying-sample-application-with-odo.adoc
@@ -9,7 +9,7 @@ This procedure deploys a sample application to the OpenShift cluster running in
 * You have installed [command]`odo`.
 For more information, see link:{odo-docs-url-installing}[Installing `odo`] in the [command]`odo` documentation.
 * The {prod} virtual machine is running.
-For more information, see <<starting-the-virtual-machine_{context}>>.
+For more information, see link:{crc-gsg-url}#starting-the-virtual-machine_gsg[Starting the virtual machine].
 
 .Procedure
 

diff --git a/docs/source/topics/proc_getting-shell-access-to-the-openshift-cluster.adoc b/docs/source/topics/proc_getting-shell-access-to-the-openshift-cluster.adoc
@@ -7,7 +7,7 @@ To access the cluster for troubleshooting or debugging purposes, follow this pro
 .Prerequisites
 
 * Enable [command]`oc` access to the cluster and log in as the `kubeadmin` user.
-For detailed steps, see <<accessing-the-openshift-cluster-with-oc_{context}>>.
+For detailed steps, see link:{crc-gsg-url}#accessing-the-openshift-cluster-with-oc_gsg[Accessing the OpenShift cluster with `oc`].
 
 .Procedure
 

diff --git a/docs/source/topics/proc_installing-codeready-containers.adoc b/docs/source/topics/proc_installing-codeready-containers.adoc
@@ -4,7 +4,7 @@
 .Prerequisites
 
 * Your host machine must meet the minimum system requirements.
-For more information, see <<minimum-system-requirements_{context}>>.
+For more information, see link:{crc-gsg-url}#minimum-system-requirements_gsg[Minimum system requirements].
 
 .Procedure
 

diff --git a/docs/source/topics/proc_starting-codeready-containers-behind-proxy.adoc b/docs/source/topics/proc_starting-codeready-containers-behind-proxy.adoc
@@ -6,7 +6,7 @@
 * To use an existing [command]`oc` binary on your host machine, export the `.testing` domain as part of the `no_proxy` environment variable.
 
 * The embedded [command]`oc` binary does not require manual settings.
-For more information about using the embedded [command]`oc` binary, see <<accessing-the-openshift-cluster-with-oc_{context}>>.
+For more information about using the embedded [command]`oc` binary, see link:{crc-gsg-url}#accessing-the-openshift-cluster-with-oc_gsg[Accessing the OpenShift cluster with `oc`].
 
 
 .Procedure

diff --git a/docs/source/topics/proc_starting-monitoring-alerting-telemetry.adoc b/docs/source/topics/proc_starting-monitoring-alerting-telemetry.adoc
@@ -8,11 +8,11 @@ Telemetry functionality is responsible for listing your cluster in the link:http
 .Prerequisites
 
 * A running {prod} virtual machine and a working [command]`oc` command.
-For more information, see <<accessing-the-openshift-cluster-with-oc_{context}>>.
+For more information, see link:{crc-gsg-url}#accessing-the-openshift-cluster-with-oc_gsg[Accessing the OpenShift cluster with `oc`].
 * You must log in through [command]`oc` as the `kubeadmin` user.
 * You must assign additional memory to the {prod} virtual machine.
 At least 12 GiB of memory (a value of `12288`) is recommended.
-For more information, see <<configuring-the-virtual-machine_{context}>>.
+For more information, see link:{crc-gsg-url}#configuring-the-virtual-machine_gsg[Configuring the virtual machine].
 
 .Procedure
 

diff --git a/docs/source/topics/proc_starting-the-virtual-machine.adoc b/docs/source/topics/proc_starting-the-virtual-machine.adoc
@@ -6,7 +6,7 @@ The [command]`{bin} start` command starts the {prod} virtual machine and OpenShi
 .Prerequisites
 
 * You set up the host machine through the [command]`{bin} setup` command.
-For more information, see <<setting-up-codeready-containers_{context}>>.
+For more information, see link:{crc-gsg-url}#setting-up-codeready-containers_gsg[Setting up {prod}].
 * You have a valid OpenShift user pull secret.
 Copy or download the pull secret from the Pull Secret section of the link:https://cloud.redhat.com/openshift/install/crc/installer-provisioned[Install on Laptop: {rh-prod}] page on cloud.redhat.com.
 +
@@ -29,5 +29,5 @@ $ {bin} start
 [NOTE]
 ====
 * The cluster takes a minimum of four minutes to start the necessary containers and Operators before serving a request.
-* If you see errors during [command]`{bin} start`, check the <<troubleshooting-codeready-containers_{context}>> section for potential solutions.
+* If you see errors during [command]`{bin} start`, check the link:{crc-gsg-url}#troubleshooting-codeready-containers_gsg[Troubleshooting {prod}] section for potential solutions.
 ====
diff --git a/docs/source/topics/proc_troubleshooting-unknown-issues.adoc b/docs/source/topics/proc_troubleshooting-unknown-issues.adoc
@@ -7,12 +7,12 @@ This involves stopping the virtual machine, deleting it, reverting changes made
 .Prerequisites
 
 * You set up the host machine through the [command]`{bin} setup` command.
-For more information, see <<setting-up-codeready-containers_{context}>>.
+For more information, see link:{crc-gsg-url}#setting-up-codeready-containers_gsg[Setting up {prod}].
 * You started {prod} through the [command]`{bin} start` command.
-For more information, see <<starting-the-virtual-machine_{context}>>.
+For more information, see link:{crc-gsg-url}#starting-the-virtual-machine_gsg[Starting the virtual machine].
 * You are using the latest {prod} release.
 Using a version earlier than {prod} 1.2.0 may result in errors related to expired x509 certificates.
-For more information, see <<troubleshooting-expired-certificates_{context}>>.
+For more information, see link:{crc-gsg-url}#troubleshooting-expired-certificates_gsg[Troubleshooting expired certificates].
 
 .Procedure
 

diff --git a/docs/source/topics/ref_minimum-system-requirements.adoc b/docs/source/topics/ref_minimum-system-requirements.adoc
@@ -16,7 +16,7 @@
 ====
 The OpenShift cluster requires these minimum resources to run in the {prod} virtual machine.
 Some workloads may require more resources.
-To assign more resources to the {prod} virtual machine, see <<configuring-the-virtual-machine_{context}>>.
+To assign more resources to the {prod} virtual machine, see link:{crc-gsg-url}#configuring-the-virtual-machine_gsg[Configuring the virtual machine].
 ====
 
 [id="minimum-system-requirements-operating-system_{context}"]
@@ -40,4 +40,4 @@ To assign more resources to the {prod} virtual machine, see <<configuring-the-vi
 * On Linux, {prod} is only supported on {rhel}/{centos} 7.5 or newer (including 8.x versions) and on the latest two stable {fed} releases.
 * When using {rhel}, the machine running {prod} must be link:https://access.redhat.com/solutions/253273[registered with the Red Hat Customer Portal].
 * {ubuntu} 18.04 LTS or newer and {debian} 10 or newer are not officially supported and may require manual set up of the host machine.
-* See <<required-software-packages_{context}>> to install the required packages for your Linux distribution.
+* See link:{crc-gsg-url}#required-software-packages_gsg[Required software packages] to install the required packages for your Linux distribution.