Upgrade GH Actions to build using the containerized solution

Signed-off-by: Rafael Sene <rafael@riscv.org>

.github/workflows/build-pdf.yml

@@ -1,79 +1,72 @@
-# This workflow installs dependencies for PDF generation, generates the PDF,
-# and uploads the PDF as an artifact.
-
-name: Build Document PDF
+name: Create Specification Document
 
+# The workflow is triggered by pull request, push to main, and manual dispatch.
 on:
-  push:
-    branches:
-      - main
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version, e.g. X.Y.Z:'
+        required: true
+        type: string
+      revision_mark: 
+          description: 'Set revision mark as Draft, Release or Stable:'
+          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
-  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-latest
 
-    env:
-      NAME: riscv-iommu
-      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
+    # Step 1: Checkout the repository
     - 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: "3.2.0"
-        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
+        submodules: 'recursive'
+
+    # Step 2: Pull the latest RISC-V Docs container image
+    - name: Pull Container
+      run: docker pull riscvintl/riscv-docs-base-container-image:latest
+
+    # Step 3: Build Files
+    - name: Build Files
+      run: make
+      env:
+        VERSION: v${{ github.event.inputs.version }}
+        REVMARK: ${{ github.event.inputs.revision_mark }}
+
+    # Step 4: Upload the built PDF files as a single artifact
+    - name: Upload Build Artifacts
       uses: actions/upload-artifact@v3
       with:
-        name: ${{ env.NAME }}.pdf
-        path: ${{ env.NAME }}.pdf
-        retention-days: 7
+        path: ${{ github.workspace }}/*.pdf
+        retention-days: 30
+
+    # Create Release
+    - name: Create Release
+      uses: softprops/action-gh-release@v1
+      with:
+        files: ${{ github.workspace }}/*.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,22 +1,65 @@
+# 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
+# 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 Doc Template for RISC-V Extensions.
+
+DATE ?= $(shell date +%Y-%m-%d)
+VERSION ?= v0.0.0
+REVMARK ?= Draft
+DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \
+riscvintl/riscv-docs-base-container-image:latest
+
 HEADER_SOURCE := header.adoc
 PDF_RESULT := riscv-iommu.pdf
 
 ASCIIDOCTOR_PDF := asciidoctor-pdf
 OPTIONS := --trace \
-           --attribute=mathematical-format=svg \
-           --attribute=pdf-fontsdir=docs-resources/fonts \
-           --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \
+           -a compress \
+           -a mathematical-format=svg \
+           -a revnumber=${VERSION} \
+           -a revremark=${REVMARK} \
+           -a revdate=${DATE} \
+           -a pdf-fontsdir=docs-resources/fonts \
+           -a pdf-style=docs-resources/themes/riscv-pdf.yml \
            --failure-level=ERROR
 REQUIRES := --require=asciidoctor-bibtex \
             --require=asciidoctor-diagram \
             --require=asciidoctor-mathematical
 
+.PHONY: all build clean build-container build-no-container
+
 all: build
 
-build:
+build: 
+	@echo "Checking if Docker is available..."
+	@if command -v docker &> /dev/null ; 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..."
+	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
+	@echo "Build completed successfully inside Docker container."
 
-	@echo "Building asciidoc"
+build-no-container:
+	@echo "Starting build..."
 	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
+	@echo "Build completed successfully."
 
 clean:
-	rm $(PDF_RESULT)
+	@echo "Cleaning up generated files..."
+	rm -f $(PDF_RESULT)
+	@echo "Cleanup completed."

readme.adoc

@@ -5,44 +5,34 @@ The specification is in Frozen state and pending ratification.
 = License
 
 This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0).
-See the https://github.com/riscv/docs-spec-template/blob/main/LICENSE[LICENSE] file for details.
+See the link:LICENSE[LICENSE] file for details.
 
 = Contributors
 
-Contributors to this specification are contained in the
-https://github.com/riscv-non-isa/riscv-iommu/blob/main/contributors.adoc[contributors.adoc] file.
+Contributors to this specification are contained in the link:contributors.adoc[contributors] file.
 
-= Dependencies
+For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file.
 
-This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on
-checkin using GitHub actions.  Workflow dependencies are located in the `dependencies` directory.
+= Dependencies
 
-For more information on AsciiDoctor, specification guidelines, or building locally, see the
-https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide].
+To build the document, you'll need the following tools installed on your system:
 
-= Cloning the project
+```
+  Make
+  asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical
+  Docker
+```
 
-This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules]
-to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project]
-to achieve a common look and feel.
+= Cloning and Building the Document
 
-When cloning this repository for the first time, you must either use
-`git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory.  Failure to clone the submodule, will result
-in the PDF build fail with an error message like the following:
+This project uses submodules to include the RISC-V documentation toolchain. 
 
-    $ make
-    asciidoctor-pdf \
-    -a toc \
-    -a compress \
-    -a pdf-style=docs-resources/themes/riscv-pdf.yml \
-    -a pdf-fontsdir=docs-resources/fonts \
-    --failure-level=ERROR \
-    -o profiles.pdf profiles.adoc
-    asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme
-    No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts
-      Use --trace for backtrace
-    make: *** [Makefile:7: profiles.pdf] Error 1
+```
+  git clone --recurse-submodule https://github.com/riscv-non-isa/riscv-iommu.git
+  cd ./riscv-zacas.git
+  make VERSION=v1.0.0 REVMARK=Draft
+```
 
-= Building the document
+`VERSION`: Represents the version of the specification being built. By default, this is set to 'v0.0.0'. You can change this to a different value, like 'v1.0.0', 'v1.1.0', etc., based on the current version of your specification.
 
-The final specification form of PDF can be generated using the `make` command.
+`REVMARK`: This represents a revision marker for the project. Its default value is 'Draft'. You may want to change this to something like 'Release', 'Stable' or 'Ratified'.