refactor to pull in latest from docs-specs-template

relates to #28

Did the following:
* pre-commit
* updated readme.adoc
* source docs moved to src
* build happens in build directory
* add html output
* update to latest for docs-resource submodule
* move imagesoutdir to Makefile since docker build can't deal with ../build for wavedrom output

Signed-off-by: Kevin Broch <kbroch@rivosinc.com>

.github/workflows/build-pdf.yml

@@ -1,3 +1,4 @@
+---
 name: Create Specification Document
 
 # The workflow is triggered by pull request, push to main, and manual dispatch.
@@ -8,18 +9,22 @@ on:
         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'
+      revision_mark:
+        description: 'Set revision mark as Draft, Release or Stable:'
+        required: true
+        type: choice
+        options:
+          - Draft
+          - Release
+          - Stable
+        default: Draft
       prerelease:
-        description: 'Tag as a pre-release?'
+        description: Tag as a pre-release?
         required: false
         type: boolean
         default: true
       draft:
-        description: 'Create release as a draft?'
+        description: Create release as a draft?
         required: false
         type: boolean
         default: false
@@ -33,41 +38,45 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    # Step 1: Checkout the repository
-    - name: Checkout repository
-      uses: actions/checkout@v3
-      with:
-        submodules: 'recursive'
+      # 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
+
+      # Override VERSION and REVMARK for manual workflow dispatch
+      - name: Update environment variables
+        run: |
+          echo "VERSION=v${{ github.event.inputs.version }}" >> "$GITHUB_ENV"
+          echo "REVMARK=${{ github.event.inputs.revision_mark }}" >> "$GITHUB_ENV"
+        if: github.event_name == 'workflow_dispatch'
 
-    # Step 2: 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
 
-    # Step 3: Build Files
-    - name: Build Files
-      run: make
-      env:
-        VERSION: v${{ github.event.inputs.version }}
-        REVMARK: ${{ github.event.inputs.revision_mark }}
+      # 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
 
-    # Step 4: Upload the built PDF files as a single artifact
-    - name: Upload Build Artifacts
-      uses: actions/upload-artifact@v3
-      with:
-        name: Build Artifacts
-        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.
+      # 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.

.github/workflows/pre-commit.yml

@@ -0,0 +1,15 @@
+---
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - uses: pre-commit/action@v3.0.0

.gitignore

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

.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-json
+      - id: check-symlinks
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+
+  - repo: local
+    hooks:
+      - id: forbidden-file-extensions
+        name: forbidden-file-extensions
+        entry: disallow these file extensions
+        language: fail
+        # Disallow other asciidoc extensions except .adoc
+        files: .*\.(asciidoc|asc)$
+
+  - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
+    rev: 0.2.3
+    hooks:
+      - id: yamlfmt
+        args: [--mapping, '2', --sequence, '4', --offset, '2']

CONTRIBUTING.md

@@ -55,4 +55,4 @@ You can manually add the DCO text to your commit body or include either -s or --
 
 Note:
 
-Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message.
+Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message.

LICENSE

@@ -49,7 +49,7 @@ exhaustive, and do not form part of our licenses.
      such as asking that all changes be marked or described.
      Although not required by our licenses, you are encouraged to
      respect those requests where reasonable. More_considerations
-     for the public: 
+     for the public:
 	wiki.creativecommons.org/Considerations_for_licensees
 
 =======================================================================
@@ -393,4 +393,3 @@ the avoidance of doubt, this paragraph does not form part of the
 public licenses.
 
 Creative Commons may be contacted at creativecommons.org.
-

Makefile

@@ -8,40 +8,69 @@
 # SPDX-License-Identifier: CC-BY-SA-4.0
 #
 # Description:
-# 
-# This Makefile is designed to automate the process of building and packaging 
+#
+# 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)
+DOCS := \
+	riscv-zabha.adoc
 VERSION ?= v0.9.1
 REVMARK ?= Stable
-DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \
-riscvintl/riscv-docs-base-container-image:latest
 
-HEADER_SOURCE := header.adoc
-PDF_RESULT := riscv-zabha.pdf
+###############################################################################
+# Changes below should be considered for https://github.com/riscv/docs-spec-template
+###############################################################################
+
+DATE ?= $(shell date +%Y-%m-%d)
+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
+
+SRC_DIR := src
+BUILD_DIR := build
 
+DOCS_PDF := $(DOCS:%.adoc=%.pdf)
+DOCS_HTML := $(DOCS:%.adoc=%.html)
+
+XTRA_ADOC_OPTS :=
 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-style=docs-resources/themes/riscv-pdf.yml \
+           -a pdf-theme=docs-resources/themes/riscv-pdf.yml \
+           -a imagesoutdir=$(BUILD_DIR)/images \
+           $(XTRA_ADOC_OPTS) \
+		   -D build \
            --failure-level=ERROR
 REQUIRES := --require=asciidoctor-bibtex \
             --require=asciidoctor-diagram \
             --require=asciidoctor-mathematical
 
-.PHONY: all build clean build-container build-no-container
+.PHONY: all build clean build-container build-no-container build-docs
 
 all: build
 
-build: 
+build-docs: $(DOCS_PDF) $(DOCS_HTML)
+
+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)
+
+build:
 	@echo "Checking if Docker is available..."
-	@if command -v docker &> /dev/null ; then \
+	@if command -v docker >/dev/null 2>&1 ; then \
 		echo "Docker is available, building inside Docker container..."; \
 		$(MAKE) build-container; \
 	else \
@@ -51,15 +80,15 @@ build:
 
 build-container:
 	@echo "Starting build inside Docker container..."
-	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
+	$(MAKE) build-docs
 	@echo "Build completed successfully inside Docker container."
 
 build-no-container:
 	@echo "Starting build..."
-	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
+	$(MAKE) SKIP_DOCKER=true build-docs
 	@echo "Build completed successfully."
 
 clean:
 	@echo "Cleaning up generated files..."
-	rm -f $(PDF_RESULT)
+	rm -rf $(BUILD_DIR)
 	@echo "Cleanup completed."

readme.adoc

@@ -5,37 +5,77 @@ support for byte and halfword atomic memory operations. It designates byte
 and halfword as valid encodings for the width field in atomic memory
 operation instructions.
 
-= License
+== License
 
-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.
+This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file.
 
-= Contributors
+== Contributors
 
-Contributors to this specification are contained in the link:contributors.adoc[contributors] file.
+The list of contributors to this specification is maintained in the link:src/contributors.adoc[contributors] file.
 
-For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file.
+For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file.
 
-= Dependencies
+== Building the Document
+
+=== Directory Structure
+
+The following directories are used to organize the contents of this repo:
+
+* `dependencies/`: software dependencies needed to build the specification
+* `docs-resources/`: resources for all specifications sourced from link:.gitmodules[git submodule]
+* `src/`: source files for the specification
+* `build/`: default directory where the build artifacts are generated
+
+=== Prerequisites
 
 To build the document, you'll need the following tools installed on your system:
 
-```
-  Make
-  asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical
-  Docker
+* Make
+* asciidoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical
+* Docker
+
+=== Cloning the Repository
+
+```shell
+git clone --recurse-submodules https://github.com/riscv/riscv-zacas.git
 ```
 
-= Cloning and Building the Document
+=== Building the Documentation
 
-This project uses submodules to include the RISC-V documentation toolchain. 
+To start the build process, run:
 
+```shell
+cd ./riscv-zacas && make build
 ```
-  git clone --recurse-submodule https://github.com/riscv/riscv-zacas.git
-  cd ./riscv-zacas.git
-  make VERSION=v1.0.0 REVMARK=Draft
+
+The link:Makefile[] script will check the availability of Docker on your system:
+
+* If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems.
+* If Docker is not available, the documentation will be built directly on your system using the installed tools.
+
+The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the `HEADER_SOURCE` variable in the Makefile.
+
+The build process utilizes several options, including theming and font settings, and generates a PDF document as output.
+
+=== Cleaning up
+
+To clean up the generated files, run:
+
+```shell
+make clean
 ```
 
-`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.
+== Enabling pre-commit checks locally
+
+The repository has some basic commit checks set up with https://pre-commit.com/[pre-commit] that will be enforced by the GitHub CI.
+To ensure these checks are also run in the local repository while making changes the following command can be run:
+[source,shell]
+----
+pip3 install pre-commit && pre-commit install
+----
 
-`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'.
+When enabling additional checks https://pre-commit.com/#plugins[by editing .pre-commit-config.yaml], it is recommended to run to newly added check on all files in the repository. This can be done with the following command:
+[source,shell]
+----
+pre-commit run --all-files
+----