Merge pull request #172 from nunix/asciidoc-migration

Initial migration to Antora

.github/dependabot.yml

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

.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Rancher Turtles documentation - publish to GitHub Pages with Lunr Search Extension
+on:
+  # Runs every hour.
+  schedule:
+    - cron: '0 * * * *'
+  # Runs whenever a change is pushed to the main branch
+  push:
+    branches: [main]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+      with:
+          submodules: recursive
+    - name: Configure Pages
+      uses: actions/configure-pages@v3
+    - name: Install Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '18'
+    - name: Install Antora with the Antora Lunr Extension
+      run: make environment
+    - name: Generate Site
+      run: make remote
+    - name: Upload Artifacts
+      uses: actions/upload-pages-artifact@v2
+      with:
+        path: build/site
+    - name: Push the static site content to gh-pages branch
+      run: |
+        git config --global user.name "${{ github.actor }}"
+        git config --global user.email "${{ github.actor }}@users.noreply.github.com"
+        mv build/site ../site-temp
+        git checkout --orphan gh-pages
+        git rm -rf .
+        rm -rf node_modules tmp
+        mv ../site-temp/* .
+        git add .
+        git commit -m "Deploy to gh-pages branch"
+        git push --force origin gh-pages
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v2

.github/workflows/test-deploy.yaml

@@ -13,13 +13,11 @@ jobs:
     name: Test deployment
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: 18
-          cache: yarn
-
-      - name: Install dependencies
-        run: yarn install --frozen-lockfile
-      - name: Test build website
-        run: yarn build
+      - name: Install Antora with the Antora Lunr Extension
+        run: make environment
+      - name: Generate Site
+        run: make local

.gitignore

@@ -1,22 +1,5 @@
-# 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/
+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.adoc

@@ -0,0 +1,92 @@
+[#turtles-product-documentation]
+= Turtles Product Documentation
+
+[#build-the-documentation-site]
+== Build the Documentation site
+
+The repository uses https://docs.antora.org/antora/latest/[Antora Playbooks] to locally or remotely build the AsciiDoc content into a static website.
+
+[#prerequisites]
+=== Prerequisites
+
+[#git]
+==== git
+
+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
+----
+
+If you don't have git installed on your machine, download and install it for your operating system from the https://git-scm.com/downloads[git downloads] page.
+
+[#node-js]
+==== 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 https://nodejs.org/en/about/releases/[active Node.js LTS version number]
+
+[,console]
+----
+node -v
+----
+
+If you don't have Node.js installed on your machine, install it, preferably via https://github.com/nvm-sh/nvm[nvm]
+
+[#clone-the-playbook-repository]
+=== Clone the Playbook repository
+
+Run the git command to clone this repository.
+
+[,console]
+----
+git clone https://github.com/rancher/turtles-product-docs.git
+----
+
+[#install-node-modules]
+=== Install node modules
+
+Open a terminal at the root of the git repository. Run the command below.
+
+[,console]
+----
+npm install
+----
+
+[#run-antora-to-build-the-static-website]
+=== Run Antora to build the static website
+
+As a local example, run the command below to build the site:
+
+[,console]
+----
+npx antora --fetch turtles-local-playbook.yml
+----
+
+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
+----
+
+[#run-antora-to-build-the-static-website-using-the-local-documentation-content]
+=== 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
+----
+
+[#makefile]
+=== 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.