Merge branch 'main' of github.com:riscv-non-isa/iopmp-spec

.github/workflows/build-pdf.yml

@@ -1,79 +1,67 @@
-# This workflow installs dependencies for PDF generation, generates the PDF,
-# and uploads the PDF as an artifact.
-
-name: Build Document PDF
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-  workflow_dispatch:
-  workflow_call:
-    outputs:
-      name:
-        description: "The base name of the pdf file (without .pdf extensions)"
-        value: ${{ jobs.build.outputs.name }}
-      pdf-name:
-        description: "The name of the pdf file (with .pdf extensions)"
-        value: ${{ jobs.build.outputs.pdf-name }}
-
-jobs:
-  build:
-    runs-on: ubuntu-22.04
-
-    env:
-      NAME: example-spec
-      APT_PACKAGES_FILE: ${{ github.workspace }}/dependencies/apt_packages.txt
-      BUNDLE_GEMFILE: ${{ github.workspace }}/dependencies/Gemfile
-      BUNDLE_BIN: ${{ github.workspace }}/bin
-      NPM_PACKAGE_FOLDER: ${{ github.workspace }}/dependencies
-    outputs:
-      name: ${{ steps.step1.outputs.name }}
-      pdf-name: ${{ steps.step2.outputs.pdf-name }}
-    steps:
-    - name: Set outputs.name
-      id: step1
-      run: echo "name=$NAME" >> $GITHUB_OUTPUT
-    - name: Set outputs.pdf-name
-      id: step2
-      run: echo "pdf-name=$NAME.pdf" >> $GITHUB_OUTPUT
-    - name: Checkout repository
-      uses: actions/checkout@v3
-      with:
-        submodules: 'true'
-    - name: Install Ubuntu packages
-      run: |
-        sudo apt-get update
-        grep -vE '^#' ${APT_PACKAGES_FILE} | xargs sudo apt-get install --yes --no-install-recommends
-    # Ruby for asciidoctor
-    - name: Setup Ruby and Gemfile content
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: "2.6"
-        bundler-cache: true
-    # Node.js for wavedrom
-    - uses: actions/cache@v3
-      with:
-        path: ~/.npm
-        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
-        restore-keys: |
-          ${{ runner.os }}-node-
-    - name: Setup Node.js
-      uses: actions/setup-node@v3
-      with:
-        node-version: '16'
-    - name: Install Node.js dependencies
-      run: npm install ${NPM_PACKAGE_FOLDER}
-    - name: Generate PDF
-      run: |
-        PATH=${PATH}:${BUNDLE_BIN}:$(npm bin) \
-        make
-    - name: Archive PDF result
-      uses: actions/upload-artifact@v3
-      with:
-        name: ${{ env.NAME }}.pdf
-        path: ${{ env.NAME }}.pdf
-        retention-days: 7
+---
+  name: Create Specification Document
+
+  # The workflow is triggered by pull request, push to main, and manual dispatch.
+  on:
+    workflow_dispatch:
+      inputs:
+        version:
+          description: 'Release version, e.g. X.Y.Z:'
+          required: true
+          type: string
+          default: Draft
+        prerelease:
+          description: Tag as a pre-release?
+          required: false
+          type: boolean
+          default: true
+        draft:
+          description: Create release as a draft?
+          required: false
+          type: boolean
+          default: false
+    pull_request:
+    push:
+      branches:
+        - main
+
+  jobs:
+    build:
+      runs-on: ubuntu-latest
+
+      steps:
+        # Checkout the repository
+        - name: Checkout repository
+          uses: actions/checkout@v4
+          with:
+            submodules: recursive
+
+        # Pull the latest RISC-V Docs container image
+        - name: Pull Container
+          run: docker pull riscvintl/riscv-docs-base-container-image:latest
+
+        # Build Files
+        - name: Build Files
+          run: make
+
+        # Upload the built PDF files as a single artifact
+        - name: Upload Build Artifacts
+          uses: actions/upload-artifact@v4
+          with:
+            name: Build Artifacts
+            path: ${{ github.workspace }}/build/*.pdf
+            retention-days: 30
+
+        # Create Release
+        - name: Create Release
+          uses: softprops/action-gh-release@v1
+          with:
+            files: ${{ github.workspace }}/build/*.pdf
+            tag_name: v${{ github.event.inputs.version }}
+            name: Release ${{ github.event.inputs.version }}
+            draft: ${{ github.event.inputs.draft }}
+            prerelease: ${{ github.event.inputs.prerelease }}
+          env:
+            GITHUB_TOKEN: ${{ secrets.GHTOKEN }}
+          if: github.event_name == 'workflow_dispatch'
+          # This condition ensures this step only runs for workflow_dispatch events.

Makefile

@@ -1,4 +1,4 @@
-# Makefile for RISC-V ISA Manuals
+# Makefile for RISC-V Doc Template
 #
 # This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
 # International License. To view a copy of this license, visit
@@ -8,53 +8,78 @@
 # 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).
+#
+# This Makefile is designed to automate the process of building and packaging
+# the Doc Template for RISC-V Extensions.
+
+DOCS := \
+	iopmp.adoc
+
+SPECNAME := iopmp
+
+ifneq ($(SKIP_DOCKER),true)
+	DOCKER_CMD := docker run --rm -v ${PWD}:/build -w /build \
+	riscvintl/riscv-docs-base-container-image:latest \
+	/bin/sh -c
+	DOCKER_QUOTE := "
+endif
 
-# Build Targets
-TARGETS := iopmp-spec
+SRC_DIR := ./
+BUILD_DIR := build
 
-# Declare phony targets
-.PHONY: all $(TARGETS) clean
+DOCS_PDF := $(DOCS:%.adoc=%.pdf)
+DOCS_HTML := $(DOCS:%.adoc=%.html)
 
-# Default target builds all
-all: $(TARGETS)
+XTRA_ADOC_OPTS :=
+ASCIIDOCTOR_PDF := asciidoctor-pdf
+ASCIIDOCTOR_HTML := asciidoctor
+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-mathematical
 
-# Build with preinstalled docker container; first install it with:
-#   docker pull riscvintl/riscv-docs-base-container-image:latest
-docker:
-	cd .. && docker run -it -v .:/build riscvintl/riscv-docs-base-container-image:latest /bin/sh -c 'cd ./build; make $(MAKEFLAGS)'
+.PHONY: all build clean build-container build-no-container build-docs
 
-# Asciidoctor options
-ASCIIDOCTOR_OPTS := -a compress \
-                    --attribute=mathematical-format=svg \
-                    --failure-level=ERROR \
-                    --require=asciidoctor-bibtex \
-                    --require=asciidoctor-diagram \
-                    --require=asciidoctor-mathematical \
-                    --trace
+all: build
 
-# Source directory
-SRCDIR := ./
+build-docs: $(DOCS_PDF) $(DOCS_HTML)
 
-PDF_RESULT := riscv-iopmp-specification.pdf
+vpath %.adoc $(SRC_DIR)
 
-# Temporary files to clean up for LaTeX build
-JUNK := *.pdf *.aux *.log *.bbl *.blg *.toc *.out *.fdb_latexmk *.fls *.synctex.gz
+%.pdf: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
 
-# IOPMP Spec Build
-iopmp-spec: riscv-iopmp-specification.pdf
+%.html: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
 
-riscv-iopmp-specification.pdf: $(SRCDIR)/header.adoc $(SRCDIR)/*.adoc
-	@echo "Building IOPMP specification"
-	rm -f $@.tmp
-	asciidoctor-pdf $(ASCIIDOCTOR_OPTS) --out-file=$@.tmp $<
-	mv $@.tmp $@
+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."
 
 clean:
 	@echo "Cleaning up generated files..."
-	rm -f $(PDF_RESULT)
-	@echo "Cleanup completed."
-
+	rm -rf $(BUILD_DIR)
+	@echo "Cleanup completed."