Makefile: add 'doc' target, include docs in install

Add a 'doc' target and 'make-docs.sh' script to build the Asciidoc documents
in 'docs/man' into installable manpages. Include these documents (and
associated symlinks) in installations from source and from platform-specific
packages.

Additionally, update 'release.yml' to install 'asciidoctor' so that the
documentation can successfully be built in that workflow.

Signed-off-by: Victoria Dye <[email protected]>

Author: vdye

.github/workflows/release.yml

@@ -47,6 +47,10 @@ jobs:
         uses: actions/setup-go@v3
         with:
           go-version: '1.19.0'
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2.1'
+      - run: gem install asciidoctor
       - name: Clone repository
         uses: actions/checkout@v3
       - name: Build the release artifact

.gitignore

@@ -2,3 +2,4 @@
 /git-bundle-web-server
 /bin/
 /_dist/
+/_docs/

Makefile

@@ -12,6 +12,7 @@ INSTALL_ROOT := /
 # Helpful paths
 BINDIR := $(CURDIR)/bin
 DISTDIR := $(CURDIR)/_dist
+DOCDIR := $(CURDIR)/_docs
 
 # Platform information
 GOOS := $(shell go env GOOS)
@@ -28,12 +29,18 @@ build:
 	@mkdir -p $(BINDIR)
 	GOOS="$(GOOS)" GOARCH="$(GOARCH)" go build -o $(BINDIR) ./...
 
+.PHONY: doc
+doc:
+	@scripts/make-docs.sh --docs="$(CURDIR)/docs/man" \
+			      --output="$(DOCDIR)"
+
 # Installation targets
 .PHONY: install
-install: build
+install: build doc
 	@echo
 	@echo "======== Installing to $(INSTALL_ROOT) ========"
 	@scripts/install.sh --bindir="$(BINDIR)" \
+			    --docdir="$(DOCDIR)" \
 			    --uninstaller="$(CURDIR)/scripts/uninstall.sh" \
 			    --allow-root \
 			    --include-symlinks \
@@ -63,10 +70,11 @@ DEBDIR := $(DISTDIR)/deb
 DEB_FILENAME := $(DISTDIR)/$(NAME)_$(VERSION)-$(PACKAGE_REVISION)_$(PACKAGE_ARCH).deb
 
 # Targets
-$(DEBDIR)/root: check-arch build
+$(DEBDIR)/root: check-arch build doc
 	@echo
 	@echo "======== Formatting package contents ========"
 	@scripts/install.sh --bindir="$(BINDIR)" \
+			    --docdir="$(DOCDIR)" \
 			    --include-symlinks \
 			    --install-root="$(DEBDIR)/root"
 
@@ -94,10 +102,11 @@ PKGDIR := $(DISTDIR)/pkg
 PKG_FILENAME := $(DISTDIR)/$(NAME)_$(VERSION)-$(PACKAGE_REVISION)_$(PACKAGE_ARCH).pkg
 
 # Targets
-$(PKGDIR)/payload: check-arch build
+$(PKGDIR)/payload: check-arch build doc
 	@echo
 	@echo "======== Formatting package contents ========"
 	@scripts/install.sh --bindir="$(BINDIR)" \
+			    --docdir="$(DOCDIR)" \
 			    --uninstaller="$(CURDIR)/scripts/uninstall.sh" \
 			    --install-root="$(PKGDIR)/payload"
 
@@ -125,3 +134,4 @@ clean:
 	go clean ./...
 	$(RM) -r $(BINDIR)
 	$(RM) -r $(DISTDIR)
+	$(RM) -r $(DOCDIR)

build/package/pkg/scripts/postinstall

@@ -18,4 +18,19 @@ do
 	ln -s "$RELATIVE_LINK_TO_BIN/$p" "$LINK_TO/$p"
 done
 
+for mandir in "$APP_ROOT"/share/man/man*/
+do
+	mdir=$(basename "$mandir")
+	LINK_TO="$INSTALL_DESTINATION/usr/local/share/man/$mdir"
+	RELATIVE_LINK_TO_MAN="../../../git-bundle-server/share/man/$mdir"
+	mkdir -p "$LINK_TO"
+
+	for manpage in "$mandir"/*
+	do
+		mpage=$(basename "$manpage")
+		rm -f "$LINK_TO/$mpage"
+		ln -s "$RELATIVE_LINK_TO_MAN/$mpage" "$LINK_TO/$mpage"
+	done
+done
+
 exit 0

scripts/install.sh

@@ -25,6 +25,10 @@ case "$i" in
 	BINDIR="${i#*=}"
 	shift # past argument=value
 	;;
+	--docdir=*)
+	DOCDIR="${i#*=}"
+	shift # past argument=value
+	;;
 	--uninstaller=*)
 	UNINSTALLER="${i#*=}"
 	shift # past argument=value
@@ -51,6 +55,9 @@ done
 if [ -z "$BINDIR" ]; then
 	die "--bindir was not set"
 fi
+if [ -z "$DOCDIR" ]; then
+	die "--docdir was not set"
+fi
 if [ -z "$INSTALL_ROOT" ]; then
 	die "--install-root was not set"
 fi
@@ -71,6 +78,14 @@ retry_root mkdir -p "$APP_ROOT"
 echo "Copying binaries..."
 retry_root cp -R "$BINDIR/." "$APP_ROOT/bin"
 
+echo "Copying manpages..."
+for N in $(find "$DOCDIR" -type f | sed -e 's/.*\.//' | sort -u)
+do
+	retry_root mkdir -p "$APP_ROOT/share/man/man$N"
+	retry_root cp -R "$DOCDIR/"*."$N" "$APP_ROOT/share/man/man$N"
+
+done
+
 # Copy uninstaller script
 if [ -n "$UNINSTALLER" ]; then
 	echo "Copying uninstall script..."
@@ -90,4 +105,20 @@ if [ -n "$INCLUDE_SYMLINKS" ]; then
 		retry_root rm -f "$LINK_TO/$p"
 		retry_root ln -s "$RELATIVE_LINK_TO_BIN/$p" "$LINK_TO/$p"
 	done
+
+	echo "Creating manpage symlinks..."
+	for mandir in "$APP_ROOT"/share/man/man*/
+	do
+		mdir=$(basename "$mandir")
+		LINK_TO="$INSTALL_ROOT/usr/local/share/man/$mdir"
+		RELATIVE_LINK_TO_MAN="../../../git-bundle-server/share/man/$mdir"
+		retry_root mkdir -p "$LINK_TO"
+
+		for manpage in "$mandir"/*
+		do
+			mpage=$(basename "$manpage")
+			retry_root rm -f "$LINK_TO/$mpage"
+			retry_root ln -s "$RELATIVE_LINK_TO_MAN/$mpage" "$LINK_TO/$mpage"
+		done
+	done
 fi

scripts/make-docs.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+die () {
+	echo "$*" >&2
+	exit 1
+}
+
+THISDIR="$( cd "$(dirname "$0")" ; pwd -P )"
+
+# Parse script arguments
+for i in "$@"
+do
+case "$i" in
+	--docs=*)
+	MAN_DIR="${i#*=}"
+	shift # past argument=value
+	;;
+	--output=*)
+	OUT_DIR="${i#*=}"
+	shift # past argument=value
+	;;
+	*)
+	die "unknown option '$i'"
+	;;
+esac
+done
+
+# Perform pre-execution checks
+if [ -z "$MAN_DIR" ]; then
+	die "--docs was not set"
+fi
+
+if [ -z "$OUT_DIR" ]; then
+	die "--output was not set"
+fi
+
+set -e
+
+if ! command -v asciidoctor >/dev/null 2>&1
+then
+	die "cannot generate man pages: asciidoctor not installed. \
+See https://docs.asciidoctor.org/asciidoctor/latest/install for \
+installation instructions."
+fi
+
+# Generate the man pages
+mkdir -p "$OUT_DIR"
+
+asciidoctor -b manpage -I "$THISDIR" -r asciidoctor-extensions.rb -D "$OUT_DIR" "$MAN_DIR/*.adoc"