Upgrade GH Actions to build using the containerized solution

Signed-off-by: Rafael Sene <[email protected]>

.github/workflows/build-pdf.yml

@@ -1,88 +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
-  pull_request:
-    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: 'Generate a pre-release.'
-        required: false 
+        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
 
-    env:
-      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
     steps:
+    # Step 1: Checkout the repository
     - name: Checkout repository
-      uses: actions/checkout@v2
-      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@v2
+      uses: actions/checkout@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@v2
-      with:
-        node-version: '14'
-    - 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@v2
+        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: riscv-cfi.pdf
-        path: riscv-cfi.pdf
-        retention-days: 7
+        path: ${{ github.workspace }}/*.pdf
+        retention-days: 30
+
+    # Create Release
     - name: Create Release
-      id: create_release
-      if: ${{ github.event.inputs.prerelease }}
-      uses: actions/create-release@v1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      uses: softprops/action-gh-release@v1
       with:
-        tag_name: ${{ github.ref_name }}
-        release_name: Release ${{ github.ref_name }}
-        draft: false
-        prerelease: true
-    - name: Upload Release Asset
-      id: upload-release-asset
-      if: ${{ github.event.inputs.prerelease }}
-      uses: actions/upload-release-asset@v1
+        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.GITHUB_TOKEN }}
-      with:
-        upload_url: ${{ steps.create_release.outputs.upload_url }}
-        asset_path: ./riscv-cfi.pdf
-        asset_name: riscv-cfi.pdf
-        asset_content_type: application/pdf
+        GITHUB_TOKEN: ${{ secrets.GHTOKEN }}
+      if: github.event_name == 'workflow_dispatch' 
+      # This condition ensures this step only runs for workflow_dispatch events.

Makefile

@@ -1,21 +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 := cfi_header.adoc
 PDF_RESULT := riscv-cfi.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:
-	@echo "Building asciidoc"
+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."
+
+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

@@ -12,48 +12,35 @@ instructions.
 
 = 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.
+This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0).
+See the link:LICENSE[LICENSE] file for details.
 
 = Contributors
 
-Contributors to this specification are contained in the 
-https://github.com/riscv/docs-spec-template/blob/main/contributors.adoc[contributors.adoc] file.
+Contributors to this specification are contained in the link:contributors.adoc[contributors] file.
 
-For instructions on how to contribute please see the
-https://github.com/riscv/docs-spec-template/blob/main/CONTRIBUTING.md[CONTRIBUTING] file.
+For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file.
 
 = Dependencies
 
-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.
+To build the document, you'll need the following tools installed on your system:
 
-For more information on AsciiDoctor, specification guidelines, or building locally, see the
-https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide].
+```
+  Make
+  asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical
+  Docker
+```
 
-= Cloning the project
+= Cloning and Building the Document
 
-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.
+This project uses submodules to include the RISC-V documentation toolchain. 
 
-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:
+```
+  git clone --recurse-submodule https://github.com/riscv/riscv-cfi.git
+  cd ./riscv-zacas.git
+  make VERSION=v1.0.0 REVMARK=Draft
+```
 
-    $ 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 
+`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.
 
-= Building the document
-
-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'.