Merge pull request #27 from kbroch-rivosinc/refactor-to-latest-spec-t…

…emplate

refactor to incorporate changes docs spec template

.github/workflows/build-pdf.yml

@@ -1,82 +1,74 @@
 ---
-# 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:
-      create_release:
-        description: Create a new Docs Dev Guide release if set to true
-        required: false
-        default: 'false'
-      target_branch:
-        description: Target Branch
+      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
-        default: main
-      release_notes:
-        description: Release Notes
+        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:
+      # Step 1: Checkout the repository
       - name: Checkout repository
         uses: actions/checkout@v3
+        with:
+          submodules: recursive
 
-      # Set the short SHA for use in artifact names
-      - name: Set short SHA
-        run: echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV
-
-      # Get the current date
-      - name: Get current date
-        run: echo "CURRENT_DATE=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
-
-      # Pull the latest RISC-V Docs container image
-      # https://github.com/riscv/riscv-docs-base-container-image
-      # https://hub.docker.com/r/riscvintl/riscv-docs-base-container-image
+      # Step 2: Pull the latest RISC-V Docs 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  files using the container
+      # Step 3: Build Files
       - 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 make
+        run: make
+        env:
+          VERSION: v${{ github.event.inputs.version }}
+          REVMARK: ${{ github.event.inputs.revision_mark }}
 
-      # Upload the priv-isa-asciidoc PDF file
-      - name: Upload docs-dev-guide.pdf
-        if: steps.build_files.outcome == 'success'
+      # Step 4: Upload the built PDF files as a single artifact
+      - name: Upload Build Artifacts
         uses: actions/upload-artifact@v3
         with:
-          name: docs-dev-guide-${{ env.SHORT_SHA }}.pdf
-          path: ${{ github.workspace }}/docs-dev-guide.pdf
-          retention-days: 7
+          name: Build Artifacts
+          path: ${{ github.workspace }}/build/*.pdf
+          retention-days: 30
 
+      # Create Release
       - name: Create Release
-        if: steps.build_files.outcome == 'success' && github.event_name == 'workflow_dispatch' && github.event.inputs.create_release == 'true'
         uses: softprops/action-gh-release@v1
         with:
-          draft: false
-          tag_name: docs-dev-guide-${{ env.SHORT_SHA }}-${{ env.CURRENT_DATE }}
-          name: ${{ env.CURRENT_DATE }}
-          body: |
-            This release was created by: ${{ github.event.sender.login }}
-            Release Notes: ${{ github.event.inputs.release_notes }}
-          files: |
-            ${{ github.workspace }}/docs-dev-guide.pdf
+          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.

.gitignore

@@ -1 +1 @@
-*.pdf
+/build/*

.gitmodules

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

Makefile

@@ -1,21 +1,70 @@
-HEADER_SOURCE := book_header.adoc
-PDF_RESULT := docs-dev-guide.pdf
-# Not all document sources are yet listed here.  Not just adoc files but
-# images/ and resources/ content.  Once they are the target can remove the
-# phony use.
-SOURCES := $(HEADER_SOURCE)
-
-all: $(PDF_RESULT)
-
-.PHONY: $(PDF_RESULT)
-$(PDF_RESULT): $(SOURCES)
-	asciidoctor-pdf \
-    --attribute=mathematical-format=svg \
-    --attribute=pdf-fontsdir=resources/fonts \
-    --attribute=pdf-theme=resources/themes/riscv-pdf.yml \
-    --failure-level=ERROR \
-    --require=asciidoctor-bibtex \
-    --require=asciidoctor-diagram \
-    --require=asciidoctor-mathematical \
-    --out-file=$@ \
-    $(HEADER_SOURCE)
+# 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
+
+SRC_DIR := src
+BUILD_DIR := build
+HEADER_SOURCE := $(SRC_DIR)/docs-dev-guide.adoc
+
+ASCIIDOCTOR_PDF := asciidoctor-pdf
+ASCIIDOCTOR_HTML := asciidoctor
+OPTIONS := --trace \
+           -a compress \
+           -a mathematical-format=svg \
+           -a revnumber=${VERSION} \
+           -a revremark=${REVMARK} \
+           -a revdate=${DATE} \
+           -a pdf-fontsdir=docs-resources/fonts \
+           -a pdf-theme=docs-resources/themes/riscv-pdf.yml \
+           -D $(BUILD_DIR) \
+           --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 "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..."
+	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)"
+	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)"
+	@echo "Build completed successfully inside Docker container."
+
+build-no-container:
+	@echo "Starting build..."
+	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)
+	$(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)
+	@echo "Build completed successfully."
+
+clean:
+	@echo "Cleaning up generated files..."
+	rm -rf $(BUILD_DIR)
+	@echo "Cleanup completed."