docs: onboard Antora

Signed-off-by: Fabrice Flore-Thébault <[email protected]>

.gitignore

@@ -1,7 +1,10 @@
 /out/
 /test/e2e/out/
 /test/integration/out/
+.cache
 /docs/build/
+/docs/node_modules
+/docs/package-lock.json
 /release/
 /release-info.json
 *.crcbundle

.vale.ini

@@ -0,0 +1,14 @@
+# Vale configuration file for `che-docs` repository.
+# See: https://docs.errata.ai/vale/config
+
+StylesPath = .cache/vale
+Packages = RedHat
+MinAlertLevel = warning
+
+[*.adoc]
+BasedOnStyles = RedHat
+RedHat.Annotations = suggestion
+RedHat.Headings = suggestion
+RedHat.Slash = warning
+RedHat.Usage = suggestion
+RedHat.Spelling = suggestion

docs/README.adoc

@@ -0,0 +1,28 @@
+= Contributing to the documentation
+
+==
+
+.Prerequisites
+* Node.js
+
+.Procedure
+
+. Open a terminal and work from the docs directory:
++
+----
+$ cd docs
+----
+
+. Install Antora:
++
+----
+$ npm i
+----
+
+. Build the documentation:
++
+----
+$ npx antora antora-playbook.yml
+----
+
+. Browse the results in `docs/build/site`.

docs/antora-playbook.yml

@@ -0,0 +1,68 @@
+---
+site:
+    title: CRC Documentation
+    start_page: crc:getting_started:introducing.adoc
+    url: https://crc.dev
+    robots: allow
+content:
+    sources:
+        -   url: ../ # Point to Git repository
+            branches: HEAD # Use local conntent
+            edit_url: "https://github.com/crc-org/crc/edit/main/{path}"
+            start_path: docs # Point to docs content
+output:
+    clean: true # Delete stale content
+runtime:
+    cache_dir: ../.cache/antora # Use a local directory rather than $HOME
+    log:
+        failure_level: warn # Fail on missing attributes
+        level: debug # Extra verbose
+ui:
+    bundle:
+        url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+        snapshot: true
+    supplemental_files: ./supplemental-ui
+urls:
+    html_extension_style: indexify
+    redirect_facility: static
+antora:
+    extensions:
+        - '@antora/lunr-extension'
+asciidoc:
+    sourcemap: true
+    attributes:
+        icons: font
+        nbsp: " "
+        # Platforms
+        rh: "Red{nbsp}Hat"
+        rhel: "Red{nbsp}Hat Enterprise{nbsp}Linux"
+        fed: Fedora
+        centos: CentOS
+        mac: macOS
+        msw: Microsoft Windows
+        debian: Debian
+        ubuntu: Ubuntu
+        openshift: OpenShift
+        ocp: OpenShift Container Platform
+        okd: OKD
+        ushift: MicroShift
+        # Product naming
+        prod: CRC
+        rh-prod: CRC
+        bin: crc
+        # Documentation naming
+        context: gsg
+        crc-gsg: CRC Getting Started Guide
+        # URLs
+        crc-download-url: https://console.redhat.com/openshift/create/local
+        crc-gsg-url: https://crc-org.github.io/crc/
+        openshift-installer-url: https://console.redhat.com/openshift/install
+        openshift-docs-url: https://docs.openshift.com/container-platform/latest
+        openshift-docs-url-landing-page: "{openshift-docs-url}/welcome/index.html#developer-activities"
+        oc-download-url: https://mirror.openshift.com/pub/openshift-v4/clients/ocp/latest/
+        odo-docs-url: "{openshift-docs-url}/cli_reference/developer_cli_odo/understanding-odo.html"
+        odo-docs-url-installing: "{openshift-docs-url}/cli_reference/developer_cli_odo/installing-odo.html"
+        odo-docs-url-single-component: "{openshift-docs-url}/cli_reference/developer_cli_odo/creating_and_deploying_applications_with_odo/creating-a-single-component-application-with-odo.html"
+        telemetry-notice-url: https://developers.redhat.com/article/tool-data-collection
+        rhel-resolved-docs: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_networking/using-different-dns-servers-for-different-domains_configuring-and-managing-networking
+

docs/antora.yml

@@ -0,0 +1,7 @@
+---
+name: crc
+title: Getting started with CRC
+version: ~ # Unversioned component version
+start_page: getting_started:introducing.adoc
+nav:
+    - modules/getting_started/nav.adoc

docs/modules/getting_started/nav.adoc

@@ -0,0 +1,10 @@
+= Getting Started Guide
+
+* xref:introducing.adoc[]
+* xref:installing.adoc[]
+* xref:using.adoc[]
+* xref:configuring.adoc[]
+* xref:networking.adoc[]
+* xref:administrative-tasks.adoc[]
+* xref:troubleshooting.adoc[]
+

docs/modules/getting_started/pages/administrative-tasks.adoc

@@ -0,0 +1,8 @@
+:description: Administrative tasks
+
+[id="administrative-tasks_{context}"]
+= Administrative tasks
+
+include::partial$proc_starting-monitoring.adoc[leveloffset=+1]
+
+include::partial$proc_enabling-override-operators.adoc[leveloffset=+1]

docs/modules/getting_started/pages/configuring.adoc

@@ -0,0 +1,12 @@
+:description: Configuring {prod}
+
+[id="configuring_{context}"]
+= Configuring {prod}
+
+include::partial$con_about-configuration.adoc[leveloffset=+1]
+
+include::partial$proc_viewing-configuration.adoc[leveloffset=+1]
+
+include::partial$proc_changing-the-selected-preset.adoc[leveloffset=+1]
+
+include::partial$proc_configuring-the-instance.adoc[leveloffset=+1]

docs/modules/getting_started/pages/installing.adoc

@@ -0,0 +1,16 @@
+:description: Installing {prod}
+
+[id="installation_{context}"]
+= Installing {prod}
+
+include::partial$ref_minimum-system-requirements.adoc[leveloffset=+1]
+
+include::partial$ref_required-software-packages.adoc[leveloffset=+1]
+
+include::partial$proc_installing.adoc[leveloffset=+1]
+
+include::partial$con_about-usage-data-collection.adoc[leveloffset=+1]
+
+include::partial$proc_configuring-usage-data-collection.adoc[leveloffset=+1]
+
+include::partial$proc_upgrading.adoc[leveloffset=+1]

docs/modules/getting_started/pages/introducing.adoc

@@ -0,0 +1,8 @@
+:description: Introducting  {prod}
+
+[id="introducing_{context}"]
+= Introducing {rh-prod}
+
+include::partial$con_about.adoc[leveloffset=+1]
+
+include::partial$con_differences-from-production-openshift-install.adoc[leveloffset=+1]

docs/modules/getting_started/pages/networking.adoc

@@ -0,0 +1,14 @@
+:description: Networking
+
+[id="networking_{context}"]
+= Networking
+
+include::partial$ref_dns-configuration.adoc[leveloffset=+1]
+
+include::partial$ref_reserved-ip-subnets.adoc[leveloffset=+1]
+
+include::partial$proc_starting-behind-proxy.adoc[leveloffset=+1]
+
+include::partial$proc_setting-up-remote-server.adoc[leveloffset=+1]
+
+include::partial$proc_connecting-to-remote-instance.adoc[leveloffset=+1]

docs/modules/getting_started/pages/troubleshooting.adoc

@@ -0,0 +1,19 @@
+:description: Troubleshooting {prod}
+
+[id="troubleshooting_{context}"]
+= Troubleshooting {rh-prod}
+
+[NOTE]
+====
+The goal of {rh-prod} is to deliver an {ocp} environment for development and testing purposes.
+Issues occurring during installation or usage of specific {openshift} applications are outside of the scope of {prod}.
+Report such issues to the relevant project.
+====
+
+include::partial$proc_getting-shell-access-to-the-openshift-cluster.adoc[leveloffset=+1]
+
+include::partial$proc_troubleshooting-expired-certificates.adoc[leveloffset=+1]
+
+include::partial$proc_troubleshooting-bundle-version-mismatch.adoc[leveloffset=+1]
+
+include::partial$proc_troubleshooting-unknown-issues.adoc[leveloffset=+1]

docs/modules/getting_started/pages/using.adoc

@@ -0,0 +1,16 @@
+[id="using_{context}"]
+= Using {prod}
+
+include::partial$con_about-presets.adoc[leveloffset=+1]
+
+include::partial$proc_setting-up.adoc[leveloffset=+1]
+
+include::partial$proc_starting-the-instance.adoc[leveloffset=+1]
+
+include::partial$assembly_accessing-the-openshift-cluster.adoc[leveloffset=+1]
+
+include::partial$proc_deploying-sample-application-with-odo.adoc[leveloffset=+1]
+
+include::partial$proc_stopping-the-instance.adoc[leveloffset=+1]
+
+include::partial$proc_deleting-the-instance.adoc[leveloffset=+1]

docs/modules/getting_started/partials/assembly_accessing-the-openshift-cluster.adoc

@@ -0,0 +1,10 @@
+[id="accessing-the-openshift-cluster_{context}"]
+= Accessing the {openshift} cluster
+
+Access the {ocp} cluster running in the {prod} instance by using the {ocp} web console or {openshift} CLI ([command]`oc`).
+
+include::partial$proc_accessing-the-openshift-web-console.adoc[leveloffset=+1]
+
+include::partial$proc_accessing-the-openshift-cluster-with-oc.adoc[leveloffset=+1]
+
+include::partial$proc_accessing-the-internal-openshift-registry.adoc[leveloffset=+1]

docs/source/topics/con_about-presets.adoc → docs/modules/getting_started/partials/con_about-presets.adoc

@@ -2,7 +2,7 @@
 = About presets
 
 [role="_abstract"]
-{prod} presets represent a managed container runtime and the lower bounds of system resources required by the instance to run it.
+{prod} presets represent a managed container runtime, and the lower bounds of system resources required by the instance to run it.
 {prod} offers presets for {ocp}, {okd}, {ushift} and the Podman container runtime.
 
 On {msw} and {mac}, the {prod} guided installer prompts you for your desired preset.
@@ -13,6 +13,5 @@ Only one preset can be active at a time.
 
 [role="_additional-resources"]
 .Additional resources
-
 * For more information about the minimum system requirements for each preset, see link:{crc-gsg-url}#minimum-system-requirements_gsg[Minimum system requirements].
 * For more information on changing the selected preset, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset].

docs/source/topics/con_about-usage-data-collection.adoc → docs/modules/getting_started/partials/con_about-usage-data-collection.adoc

@@ -7,6 +7,5 @@ Consent for usage data collection can be granted or revoked by you at any time.
 
 [role="_additional-resources"]
 .Additional resources
-
 * For more information about collected data, see the {rh} link:{telemetry-notice-url}[Telemetry data collection notice].
 * To grant or revoke consent for usage data collection, see link:{crc-gsg-url}#configuring-usage-data-collection_gsg[Configuring usage data collection].

docs/source/topics/con_differences-from-production-openshift-install.adoc → docs/modules/getting_started/partials/con_differences-from-production-openshift-install.adoc

@@ -5,17 +5,17 @@ The {openshift} preset for {rh-prod} provides a regular {ocp} installation with
 
 * **The {ocp} cluster is ephemeral and is not intended for production use.**
 * **{prod} does not have a supported upgrade path to newer {ocp} versions.**
-Upgrading the {ocp} version may cause issues that are difficult to reproduce.
-* It uses a single node which behaves as both a control plane and worker node.
+Upgrading the {ocp} version might cause issues that are difficult to reproduce.
+* It uses a single node, which behaves as both a control plane and worker node.
 * It disables the Cluster Monitoring Operator by default.
 This disabled Operator causes the corresponding part of the web console to be non-functional.
 * The {ocp} cluster runs in a virtual machine known as an __instance__.
-This may cause other differences, particularly with external networking.
+This might cause other differences, particularly with external networking.
 
 The {ocp} cluster provided by {prod} also includes the following non-customizable cluster settings.
 These settings should not be modified:
 
-* Use of the ***.crc.testing** domain.
+* Use the ***.crc.testing** domain.
 * The address range used for internal cluster communication.
 ** The cluster uses the **172** address range.
 This can cause issues when, for example, a proxy is run in the same address space.

docs/source/topics/proc_accessing-the-internal-openshift-registry.adoc → docs/modules/getting_started/partials/proc_accessing-the-internal-openshift-registry.adoc

@@ -6,7 +6,6 @@ This internal container image registry can be used as a publication target for l
 To access the internal {ocp} registry, follow these steps.
 
 .Prerequisites
-
 * {prod} is configured to use the {openshift} preset.
 For more information, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset].
 * A running {prod} instance.
@@ -15,7 +14,6 @@ For more information, see link:{crc-gsg-url}#starting-the-instance_gsg[Starting
 For more information, see link:{crc-gsg-url}#accessing-the-openshift-cluster-with-oc_gsg[Accessing the {openshift} cluster with the {openshift} CLI].
 
 .Procedure
-
 . Check which user is logged in to the cluster:
 +
 [subs="+quotes,attributes"]

docs/source/topics/proc_accessing-the-openshift-cluster-with-oc.adoc → docs/modules/getting_started/partials/proc_accessing-the-openshift-cluster-with-oc.adoc

@@ -4,14 +4,12 @@
 Access the {ocp} cluster managed by {prod} by using the {openshift} CLI ([command]`oc`).
 
 .Prerequisites
-
 * {prod} is configured to use the {openshift} preset.
 For more information, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset].
 * A running {prod} instance.
 For more information, see link:{crc-gsg-url}#starting-the-instance_gsg[Starting the instance].
 
 .Procedure
-
 . Run the [command]`{bin} oc-env` command to print the command needed to add the cached [command]`oc` executable to your `$PATH`:
 +
 [subs="+quotes,attributes"]
@@ -53,5 +51,4 @@ $ oc get co
 See link:{crc-gsg-url}#troubleshooting_gsg[Troubleshooting {prod}] if you cannot access the {ocp} cluster managed by {prod}.
 
 .Additional resources
-
 * The link:https://docs.openshift.com/container-platform/latest/applications/projects/working-with-projects.html[{ocp} documentation] covers the creation of projects and applications.

docs/source/topics/proc_accessing-the-openshift-web-console.adoc → docs/modules/getting_started/partials/proc_accessing-the-openshift-web-console.adoc

@@ -8,14 +8,12 @@ Use the `developer` user for creating projects or {openshift} applications and f
 Use the `kubeadmin` user only for administrative tasks such as creating new users or setting roles.
 
 .Prerequisites
-
 * {prod} is configured to use the {openshift} preset.
 For more information, see link:{crc-gsg-url}#changing-the-selected-preset_gsg[Changing the selected preset].
 * A running {prod} instance.
 For more information, see link:{crc-gsg-url}#starting-the-instance_gsg[Starting the instance].
 
 .Procedure
-
 . To access the {ocp} web console with your default web browser, run the following command:
 +
 [subs="+quotes,attributes"]
@@ -34,5 +32,4 @@ $ {bin} console --credentials
 See link:{crc-gsg-url}#troubleshooting_gsg[Troubleshooting {prod}] if you cannot access the {ocp} cluster managed by {prod}.
 
 .Additional resources
-
 * The link:https://docs.openshift.com/container-platform/latest/applications/projects/working-with-projects.html[{ocp} documentation] covers the creation of projects and applications.

docs/source/topics/proc_changing-the-selected-preset.adoc → docs/modules/getting_started/partials/proc_changing-the-selected-preset.adoc

@@ -15,7 +15,6 @@ To enable preset changes, you must delete the existing instance and start a new
 ====
 
 .Procedure
-
 * Change the selected preset from the command line:
 +
 [subs="+quotes,attributes"]
@@ -27,5 +26,4 @@ Valid preset names are `openshift` for {ocp}, `okd` for {okd} and `podman` for t
 
 [role="_additional-resources"]
 .Additional resources
-
 * For more information about the minimum system requirements for each preset, see link:{crc-gsg-url}#minimum-system-requirements_gsg[Minimum system requirements].

docs/source/topics/proc_configuring-the-instance.adoc → docs/modules/getting_started/partials/proc_configuring-the-instance.adoc

@@ -12,7 +12,6 @@ To enable configuration changes, you must stop the running instance and start it
 ====
 
 .Procedure
-
 * To configure the number of vCPUs available to the instance:
 +
 [subs="+quotes,attributes"]

docs/source/topics/proc_configuring-usage-data-collection.adoc → docs/modules/getting_started/partials/proc_configuring-usage-data-collection.adoc

@@ -10,7 +10,6 @@ The change will take effect next time you run the [command]`{bin} start` command
 ====
 
 .Procedure
-
 * To manually enable telemetry, run the following command:
 +
 [subs="+quotes,attributes"]
@@ -27,5 +26,4 @@ $ {bin} config set consent-telemetry no
 
 [role="_additional-resources"]
 .Additional resources
-
 * For more information about the collected data, see the {rh} link:{telemetry-notice-url}[Telemetry data collection notice].