From 90595a9f640dea632a9a4304f8561cff0ddc6db6 Mon Sep 17 00:00:00 2001
From: Sebastian Davids <sdavids@gmx.de>
Date: Mon, 30 Sep 2024 18:12:33 +0200
Subject: [PATCH] feat: add antora_build script

Signed-off-by: Sebastian Davids <sdavids@gmx.de>
---
 docs/user-guide/modules/ROOT/nav.adoc         |   1 +
 .../pages/scripts/asciidoc/antora-build.adoc  | 184 ++++++++++++++++++
 .../scripts/asciidoc/asciidoc-html-build.adoc |   3 +-
 .../ROOT/pages/scripts/asciidoc/asciidoc.adoc |   1 +
 scripts/asciidoc/antora_build.sh              |  98 ++++++++++
 5 files changed, 286 insertions(+), 1 deletion(-)
 create mode 100644 docs/user-guide/modules/ROOT/pages/scripts/asciidoc/antora-build.adoc
 create mode 100755 scripts/asciidoc/antora_build.sh

diff --git a/docs/user-guide/modules/ROOT/nav.adoc b/docs/user-guide/modules/ROOT/nav.adoc
index 69716de33..242d3a986 100644
--- a/docs/user-guide/modules/ROOT/nav.adoc
+++ b/docs/user-guide/modules/ROOT/nav.adoc
@@ -6,6 +6,7 @@
 * xref:index.adoc[]
 * xref:scripts/scripts.adoc[]
 ** xref:scripts/asciidoc/asciidoc.adoc[]
+*** xref:scripts/asciidoc/antora-build.adoc[]
 *** xref:scripts/asciidoc/asciidoc-html-build.adoc[]
 *** xref:scripts/asciidoc/asciidoc-pdf-build.adoc[]
 ** xref:scripts/cert/cert.adoc[]
diff --git a/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/antora-build.adoc b/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/antora-build.adoc
new file mode 100644
index 000000000..e3b7df1ea
--- /dev/null
+++ b/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/antora-build.adoc
@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: © 2024 Sebastian Davids <sdavids@gmx.de>
+// SPDX-License-Identifier: Apache-2.0
+= antora_build
+:script_url: https://github.com/sdavids/sdavids-shell-misc/blob/main/scripts/asciidoc/antora_build.sh
+
+{script_url}[This script^] will create a documentation site with https://docs.antora.org/antora/latest/[Antora] from a given source directory.
+
+The following parameters are optional:
+
+`f` :: delete the output directory before site creation
+`o` :: the output directory (`$PWD/build` if not given)
+`p` :: path to the Antora playbook (`docs/antora-playbook.yml` if not given); relative to the source directory `-s`
+`s` :: the source directory (`$PWD` if not given)
++
+[IMPORTANT]
+====
+The source directory https://docs.antora.org/antora/latest/content-source-repositories/#git-and-content-sources[needs to be a Git repository root] with at least one commit.
+====
+
+[TIP]
+====
+Copy this script into your project:
+
+[,shell]
+----
+<project root directory>
+└── scripts
+    ├── antora_build.sh
+    ├── ...
+----
+
+See: <<antora-build-example>>
+====
+
+== Usage
+
+[,console]
+----
+$ scripts/asciidoc/antora_build.sh
+----
+
+[,shell]
+----
+$ tree --noreport -I .git /tmp/example
+/tmp/example
+└── docs
+    ├── antora-playbook.yml
+    ├── antora.yml
+    └── modules
+        └── ROOT
+            ├── nav.adoc
+            └── pages
+                └── index.adoc
+$ scripts/asciidoc/antora_build.sh -s /tmp/example -o /tmp/example/build
+$ tree --noreport -I .git -L 2 /tmp/example
+/tmp/example
+├── build
+│   ├── _
+│   └── example
+└── docs
+    ├── antora-playbook.yml
+    ├── antora.yml
+    └── modules
+
+$ tree --noreport -I .git /tmp/example2
+/tmp/example2
+├── antora
+│   └── antora-playbook.yml
+└── docs
+    ├── antora.yml
+    └── modules
+        └── ROOT
+            ├── nav.adoc
+            └── pages
+                └── index.adoc
+$ scripts/asciidoc/antora_build.sh -s /tmp/example2 -o /tmp/example2/build -p antora/antora-playbook.yml
+$ tree --noreport -I .git -L 2 /tmp/example2/
+/tmp/example2/
+├── antora
+│   └── antora-playbook.yml
+├── build
+│   ├── _
+│   └── example
+└── docs
+    ├── antora.yml
+    └── modules
+----
+
+[#antora-build-example]
+== Example
+
+[,shell]
+----
+$ mkdir -p /tmp/example/scripts
+$ cp scripts/asciidoc/antora_build.sh /tmp/example/scripts
+$ cd /tmp/example
+$ echo 'build' >.gitignore
+$ git init -q
+$ git commit --allow-empty -q -m initial                                  <1>
+$ mkdir -p docs/modules/ROOT/pages
+$ echo '= Example' >docs/modules/ROOT/pages/index.adoc
+$ echo '* xref:index.adoc[]' >docs/modules/ROOT/nav.adoc
+$ cat << 'EOF' >docs/antora.yml
+---
+name: example
+version: ~                                                                <2>
+nav:
+  - modules/ROOT/nav.adoc
+EOF
+$ cat << 'EOF' >docs/antora-playbook.yml
+---
+content:
+  sources:
+    - url: ./..                                                           <3>
+      start_path: docs                                                    <4>
+ui:
+  bundle:
+    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
+    snapshot: true
+EOF
+$ tree --noreport -I .git /tmp/example
+/tmp/example
+├── docs
+│   ├── antora-playbook.yml
+│   ├── antora.yml
+│   └── modules
+│       └── ROOT
+│           ├── nav.adoc
+│           └── pages
+│               └── index.adoc
+└── scripts
+    └── antora_build.sh
+$ scripts/antora_build.sh
+$ tree --noreport -I .git -I '*.svg' -I '*.woff' -I '*.woff2' /tmp/example/
+/tmp/example/
+├── build
+│ ├── _
+│ │ ├── css
+│ │ │ └── site.css
+│ │ ├── font
+│ │ ├── img
+│ │ └── js
+│ │     ├── site.js
+│ │     └── vendor
+│ │         └── highlight.js
+│ └── example
+│     └── index.html
+├── docs
+│ ├── antora-playbook.yml
+│ ├── antora.yml
+│ └── modules
+│     └── ROOT
+│         ├── nav.adoc
+│         └── pages
+│             └── index.adoc
+└── scripts
+    └── antora_build.sh
+----
+
+⇒ `build/example/index.html`
+
+<1> a https://docs.antora.org/antora/latest/playbook/content-source-url/#local-urls[local content source root] needs at least one commit
+<2> an https://docs.antora.org/antora/latest/component-with-no-version/[unversioned] component
+<3> `url` needs to point to the Git repository root, i.e. the directory with the `.git` subdirectory; this is relative to `antora-playbook.yml`
+<4> `start_path` points to where the component (`antora.yml`) can be found; relative to `url`
+
+== Prerequisites
+
+* xref:developer-guide::dev-environment/dev-installation.adoc#docker[Docker]
+
+== Related Scripts
+
+* xref:scripts/asciidoc/asciidoc-html-build.adoc[]
+
+== More Information
+
+* https://docs.antora.org/antora/latest/[Antora]
+* https://docs.antora.org/antora/latest/standard-directories/[Antora - Standard File and Directory Set]
+* https://docs.antora.org/antora/latest/content-source-repositories/[Antora - Repositories and Content Source Roots]
+* https://docs.antora.org/antora/latest/playbook/content-source-url/#local-urls[Antora - Use local content repositories]
+* https://docs.antora.org/antora/latest/component-version-descriptor/[Antora - What’s antora.yml?]
+* https://docs.antora.org/antora/latest/component-with-no-version/[Antora - Define a Component with No Version]
+* https://docs.antora.org/antora/latest/playbook/[Antora - Playbook]
+* https://docs.antora.org/antora/latest/playbook/#relative-paths-in-a-playbook[Antora - Playbook - Relative paths in a playbook]
diff --git a/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/asciidoc-html-build.adoc b/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/asciidoc-html-build.adoc
index d303fefde..391e423fe 100644
--- a/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/asciidoc-html-build.adoc
+++ b/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/asciidoc-html-build.adoc
@@ -37,7 +37,7 @@ If you want to use custom fonts, this script assumes that the `woff2` fonts are
 
 [TIP]
 ====
-Depending on your use case, you might want to use https://docs.antora.org/antora/latest/[Antora] instead of this script.
+Depending on your use case, you might want to use xref:scripts/asciidoc/antora-build.adoc[] instead of this script.
 ====
 
 == Usage
@@ -199,6 +199,7 @@ $ ../asciidoc_html_build.sh
 
 == Related Scripts
 
+* xref:scripts/asciidoc/antora-build.adoc[]
 * xref:scripts/asciidoc/asciidoc-pdf-build.adoc[]
 
 == More Information
diff --git a/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/asciidoc.adoc b/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/asciidoc.adoc
index 397284b56..e794e73ad 100644
--- a/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/asciidoc.adoc
+++ b/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/asciidoc.adoc
@@ -4,5 +4,6 @@
 
 This section contains scripts related to https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc]:
 
+xref:scripts/asciidoc/antora-build.adoc[]:: create a documentation site with Antora from a given directory
 xref:scripts/asciidoc/asciidoc-html-build.adoc[]:: typeset the documents of a given directory into HTML
 xref:scripts/asciidoc/asciidoc-pdf-build.adoc[]:: typeset the documents of a given directory into PDFs
diff --git a/scripts/asciidoc/antora_build.sh b/scripts/asciidoc/antora_build.sh
new file mode 100755
index 000000000..9e5877bab
--- /dev/null
+++ b/scripts/asciidoc/antora_build.sh
@@ -0,0 +1,98 @@
+#!/usr/bin/env sh
+
+# SPDX-FileCopyrightText: © 2024 Sebastian Davids <sdavids@gmx.de>
+# SPDX-License-Identifier: Apache-2.0
+
+set -eu
+
+# https://docs.antora.org/antora/latest/whats-new/
+readonly antora_version='3.1.10'
+
+# https://stackoverflow.com/a/3915420
+# https://stackoverflow.com/questions/3915040/how-to-obtain-the-absolute-path-of-a-file-via-shell-bash-zsh-sh#comment100267041_3915420
+command -v realpath >/dev/null 2>&1 || realpath() {
+  if [ -h "$1" ]; then
+    # shellcheck disable=SC2012
+    ls -ld "$1" | awk '{ print $11 }'
+  else
+    echo "$(
+      cd "$(dirname -- "$1")" >/dev/null
+      pwd -P
+    )/$(basename -- "$1")"
+  fi
+}
+
+while getopts ':fo:p:s:' opt; do
+  case "${opt}" in
+    f)
+      force='true'
+      ;;
+    o)
+      build_dir="${OPTARG}"
+      ;;
+    p)
+      playbook_path="${OPTARG}"
+      ;;
+    s)
+      src_dir="${OPTARG}"
+      ;;
+    ?)
+      echo "Usage: $0 [-s <sourceDirectory>] [-o <outputDirectory>] [-p <pathToAntoraPlaybook>] [-f]" >&2
+      exit 1
+      ;;
+  esac
+done
+
+src_dir="${src_dir:-$PWD}"
+
+if [ ! -d "${src_dir}" ]; then
+  printf "The source directory '%s' does not exist\n" "${src_dir}" >&2
+  exit 1
+fi
+
+src_dir="$(realpath "${src_dir}")"
+readonly src_dir
+
+readonly force="${force:-false}"
+
+playbook_path="${playbook_path:-docs/antora-playbook.yml}"
+readonly playbook_path
+
+build_dir="${build_dir:-$PWD/build}"
+
+if [ "${force}" = 'true' ] \
+  && [ -d "${build_dir}" ] \
+  && [ "${build_dir}" != "$PWD" ]; then
+
+  rm -rf "${build_dir}"
+fi
+
+mkdir -p "${build_dir}"
+
+build_dir="$(realpath "${build_dir}")"
+readonly build_dir
+
+cache_dir="${HOME}/.cache/antora"
+if [ "$(uname)" = 'Darwin' ]; then
+  cache_dir="${HOME}/Library/Application Support/antora/cache"
+fi
+if [ -n "${XDG_CACHE_HOME+x}" ]; then
+  cache_dir="${XDG_CACHE_HOME}/antora"
+fi
+readonly cache_dir
+
+mkdir -p "${cache_dir}"
+
+docker container run \
+  --user "$(id -u):$(id -g)" \
+  --rm \
+  --read-only \
+  --security-opt='no-new-privileges=true' \
+  --cap-drop=all \
+  --mount "type=bind,src=${src_dir},dst=/antora,ro" \
+  --mount "type=bind,src=${build_dir},dst=/antora_build" \
+  --mount "type=bind,src=${cache_dir},dst=/antora_cache" \
+  "antora/antora:${antora_version}" \
+  --cache-dir=/antora_cache \
+  --to-dir=/antora_build \
+  "${playbook_path}"