diff --git a/docs/user-guide/modules/ROOT/nav.adoc b/docs/user-guide/modules/ROOT/nav.adoc index 56146e7ea..30748a64f 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..8d3d6df69 --- /dev/null +++ b/docs/user-guide/modules/ROOT/pages/scripts/asciidoc/antora-build.adoc @@ -0,0 +1,184 @@ +// SPDX-FileCopyrightText: © 2024 Sebastian Davids +// 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] +---- + +└── scripts + ├── antora_build.sh + ├── ... +---- + +See: <> +==== + +== 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..9d5d37417 --- /dev/null +++ b/scripts/asciidoc/antora_build.sh @@ -0,0 +1,106 @@ +#!/usr/bin/env sh + +# SPDX-FileCopyrightText: © 2024 Sebastian Davids +# SPDX-License-Identifier: Apache-2.0 + +set -eu + +# https://docs.antora.org/antora/latest/whats-new/ +readonly antora_version='3.1.9' + +# 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 ] [-o ] [-p ] [-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}" + +# https://gitlab.com/antora/docker-antora/-/issues/28 +if [ "$(uname)" = 'Darwin' ]; then + platform='--platform=linux/amd64' +else + platform='' +fi +readonly platform + +docker container run "${platform}" \ + --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}"