align with build workflow in docs-spec-template

related to #1448

Signed-off-by: Kevin Broch <[email protected]>

.github/workflows/isa-build.yml

@@ -29,6 +29,8 @@ jobs:
     # Checkout the repository
     - name: Checkout repository
       uses: actions/checkout@v4
+      with:
+        submodules: recursive
 
     # Set the short SHA for use in artifact names
     - name: Set short SHA
@@ -43,16 +45,13 @@ jobs:
     # https://hub.docker.com/r/riscvintl/riscv-docs-base-container-image
     - name: Pull Container
       id: pull_container_image
-      run: |
-        docker pull riscvintl/riscv-docs-base-container-image:latest
+      run: docker pull riscvintl/riscv-docs-base-container-image:latest
 
     # Build PDF and HTML files using the container
     - name: Build Files
       id: build_files
       if: steps.pull_container_image.outcome == 'success'
-      run: |
-        docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \
-        /bin/sh -c 'export LANG=C.utf8; cd ./build && make'
+      run:  /bin/sh -c 'export LANG=C.utf8; make -j'
 
     # Upload the riscv-privileged PDF file
     - name: Upload riscv-privileged.pdf
@@ -127,4 +126,4 @@ jobs:
           ${{ github.workspace }}/build/riscv-unprivileged.epub
       env:
         GITHUB_TOKEN: ${{ secrets.GHTOKEN }}
-
+

.gitignore

@@ -1,5 +1,5 @@
 .DS_Store
 .*.swp
 .vscode
-src/.asciidoctor
-src/diag*
+/build/*
+/images/*

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "docs-resources"]
+	path = docs-resources
+	url = https://github.com/riscv/docs-resources

Makefile

@@ -0,0 +1,103 @@
+# Makefile for RISC-V ISA Manuals
+#
+# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+# International License. To view a copy of this license, visit
+# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to
+# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+#
+# SPDX-License-Identifier: CC-BY-SA-4.0
+#
+# Description:
+# 
+# This Makefile is designed to automate the process of building and packaging 
+# the documentation for RISC-V ISA Manuals. It supports multiple build targets 
+# for generating documentation in various formats (PDF, HTML, EPUB).
+#
+# Building with a preinstalled docker container is recommended.
+# Install by running:
+#
+#   docker pull riscvintl/riscv-docs-base-container-image:latest
+#
+
+DOCS := \
+	riscv-privileged.adoc \
+	riscv-unprivileged.adoc
+
+DATE ?= $(shell date +%Y-%m-%d)
+DOCKER_IMG := riscvintl/riscv-docs-base-container-image:latest
+ifneq ($(SKIP_DOCKER),true)
+	DOCKER_CMD := docker run --rm -v ${PWD}:/build -w /build \
+	${DOCKER_IMG} \
+	/bin/sh -c
+	DOCKER_QUOTE := "
+endif
+
+SRC_DIR := src
+BUILD_DIR := build
+
+DOCS_PDF := $(DOCS:%.adoc=%.pdf)
+DOCS_HTML := $(DOCS:%.adoc=%.html)
+DOCS_EPUB := $(DOCS:%.adoc=%.epub)
+
+XTRA_ADOC_OPTS :=
+ASCIIDOCTOR_PDF := asciidoctor-pdf
+ASCIIDOCTOR_HTML := asciidoctor
+ASCIIDOCTOR_EPUB := asciidoctor-epub3
+OPTIONS := --trace \
+           -a compress \
+           -a mathematical-format=svg \
+           -a pdf-fontsdir=docs-resources/fonts \
+           -a pdf-theme=docs-resources/themes/riscv-pdf.yml \
+           $(XTRA_ADOC_OPTS) \
+		   -D build \
+           --failure-level=ERROR
+REQUIRES := --require=asciidoctor-bibtex \
+            --require=asciidoctor-diagram \
+			--require=asciidoctor-lists \
+            --require=asciidoctor-mathematical
+
+.PHONY: all build clean build-container build-no-container build-docs
+
+all: build
+
+build-docs: $(DOCS_PDF) $(DOCS_HTML) $(DOCS_EPUB)
+
+vpath %.adoc $(SRC_DIR)
+
+%.pdf: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
+
+%.html: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
+
+%.epub: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_EPUB) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
+
+build:
+	@echo "Checking if Docker is available..."
+	@if command -v docker >/dev/null 2>&1 ; then \
+		echo "Docker is available, building inside Docker container..."; \
+		$(MAKE) build-container; \
+	else \
+		echo "Docker is not available, building without Docker..."; \
+		$(MAKE) build-no-container; \
+	fi
+
+build-container:
+	@echo "Starting build inside Docker container..."
+	$(MAKE) build-docs
+	@echo "Build completed successfully inside Docker container."
+
+build-no-container:
+	@echo "Starting build..."
+	$(MAKE) SKIP_DOCKER=true build-docs
+	@echo "Build completed successfully."
+
+# Update docker image to latest
+docker-pull-latest:
+	docker pull ${DOCKER_IMG}
+
+clean:
+	@echo "Cleaning up generated files..."
+	rm -rf $(BUILD_DIR)
+	@echo "Cleanup completed."