Initial migration to Antora

The MD files have been migrated to AsciiDoc and Docusaurus framework replaced by Antora.

Some few changes to the visuals (logo, project name) have been applied.

Signed-off-by: Nuno do Carmo [email protected]

.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+
+updates:
+  - package-ecosystem: gitsubmodule
+    schedule:
+        interval: "daily"
+    directory: /
+

.gitignore

@@ -1,22 +1,6 @@
-# Dependencies
-/node_modules
-
-# Production
-/build
-
-# Generated files
-.docusaurus
-.cache-loader
-
-# Misc
-.DS_Store
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-
-.direnv/
+tmp/
+docs/
+node_modules/
+build/
+.vscode/
+.DS_Store

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "product-docs-supplemental-files"]
+	path = product-docs-supplemental-files
+	url = https://github.com/rancher/product-docs-supplemental-files.git

CODEOWNERS

@@ -0,0 +1 @@
+* @rancher/Docs

Makefile

@@ -1,33 +1,23 @@
-# Copyright 2023 SUSE.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
+local:
+	mkdir -p tmp
+	npx antora --version
+	npx antora --stacktrace --log-format=pretty --log-level=info \
+		turtles-local-playbook.yml \
+		2>&1 | tee tmp/local-build.log 2>&1
 
-# If you update this file, please follow
-# https://www.thapaliya.com/en/writings/well-documented-makefiles/
+remote:
+	mkdir -p tmp
+	npm install && npm update
+	npx antora --version
+	npx antora --stacktrace --log-format=pretty \
+		playbook-remote.yml \
+		2>&1 | tee tmp/remote-build.log 2>&1
 
-# Ensure Make is run with bash shell as some syntax below is bash-specific
-SHELL:=/usr/bin/env bash
+clean:
+	rm -rf build
 
-# Enables shell script tracing. Enable by running: TRACE=1 make <target>
-TRACE ?= 0
+environment:
+	npm install && npm update
 
-.PHONY: generate-doctoc
-generate-doctoc:
-	TRACE=$(TRACE) ./hack/generate-doctoc.sh
-
-.PHONY: verify-doctoc
-verify-doctoc: generate-doctoc
-	@if !(git diff --quiet HEAD); then \
-		git diff; \
-		echo "doctoc is out of date, run make generate-doctoc"; exit 1; \
-	fi
+preview:
+	npx http-server build/site -c-1

README.md

@@ -1,45 +1,91 @@
-# Rancher Turtles Documentation
+# Turtles Product Documentation
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+## Build the Documentation site
 
-### Installation
+The repository uses [Antora Playbooks](https://docs.antora.org/antora/latest/) to locally or remotely build the AsciiDoc content into a static website.
 
-```
-$ yarn
-```
+### Prerequisites
+
+#### git
 
-### Local Development
+You need git to get the source code of this repository. Run the command below to check whether git is installed on your machine.
 
+```console
+git --version
 ```
-$ yarn start
+
+If you don't have git installed on your machine, download and install it for your operating system from the [git downloads](https://git-scm.com/downloads) page.
+
+#### Node.js
+
+Antora requires an active long term support (LTS) release of Node.js. Run the command below to check if you have Node.js installed, and which version. This command should return an [active Node.js LTS version number](https://nodejs.org/en/about/releases/)
+
+```console
+node -v
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+If you don't have Node.js installed on your machine, install it, preferably via [nvm](https://github.com/nvm-sh/nvm)
+
+### Clone the Playbook repository
 
-### Build
+Run the git command to clone this repository.
 
+```console
+git clone https://github.com/rancher/turtles-product-docs.git
 ```
-$ yarn build
+
+This playbook repository uses a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to get the custom Antora supplemental files that provide a custom GUI theme for the documentation website. Run the command below to get the submodule.
+
+```console
+git submodule update --init
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+### Install node modules
 
-### Versioning
+Open a terminal at the root of the git repository. Run the command below.
 
-This project follows docusaurus [versioning](https://docusaurus.io/docs/versioning#configuring-versioning-behavior) guidelines, including the process of [archiving](https://docusaurus.io/docs/versioning#keep-the-number-of-versions-small) the old versions.
+```console
+npm install
+```
 
-### Deployment
+### Run Antora to build the static website
 
-Using SSH:
+As a local example, run the command below to build the site:
 
-```
-$ USE_SSH=true yarn deploy
+```console
+npx antora --fetch turtles-local-playbook.yml
 ```
 
-Not using SSH:
+Navigate to the `./build/site` directory and open the index.html file in your browser to view and navigate the documentation site.
 
+Alternatively, run the below command first and then open `http://127.0.0.1:8080/` in your browser for a web server preview:
+
+```console
+make preview
 ```
-$ GIT_USER=<Your GitHub username> yarn deploy
+
+### Run Antora to build the static website using the local documentation content
+
+The command provided in the previous section fetches documentation content of the products from their respective remote GitHub repositories. If you want the playbook to use the documentation content from your local machine instead you can do so with `product-docs-playbook-local.yml`.
+
+Clone all the individual product documentation Github repositories one level above the current playbook repository.
+
+As an example, run the command below to use the local `turtles-local-playbook.yml` file.
+
+```console
+npx antora --fetch turtles-local-playbook.yml
 ```
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+### Makefile
+
+The Makefile can also be used to set up your environment, build the local and remote static site, and clean your build output directory.
+
+## How to report issues related to the SUSE Rancher Product Documentation
+
+### If you are a SUSE Rancher Customer
+
+It is recommended to report the issue via the [SUSE Customer Center](https://scc.suse.com/)
+
+### If you are a SUSE Internal Employee
+
+It is recommended to file a Jira ticket. If you do not have access to Jira then you can file a GitHub ticket on the respective product documentation repository.