refactor spec to match current spec-template (no spec content changes)

the following was done:
* update docs-resources to point to latest which updated fonts
* add pre-commit hook checks
* move all doc src to src directory
* create build dir for all build artifacts to land in
* build html version
* update readme to reflect all these changes

Signed-off-by: Kevin Broch <[email protected]>

.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,18 @@ 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: string
+        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,40 +34,41 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    # Step 1: Checkout the repository
-    - name: Checkout repository
-      uses: actions/checkout@v3
-      with:
-        submodules: 'recursive'
+      # Step 1: Checkout the repository
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          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 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 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:
-        path: ${{ github.workspace }}/*.pdf
-        retention-days: 30
+      # Step 4: 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 }}/*.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/[email protected]

.gitignore

@@ -1 +1 @@
-
+/build/*

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+---
+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
+        exclude: \.svg$
+      - 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,8 +8,8 @@
 # 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)
@@ -18,21 +18,22 @@ REVMARK ?= Draft
 DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \
 riscvintl/riscv-docs-base-container-image:latest
 
-HEADER_SOURCE := server_soc_header.adoc
-PDF_RESULT := riscv-server-soc.pdf
-
-TS_HEADER_SOURCE := server_soc_ts_header.adoc
-TS_PDF_RESULT := riscv-server-soc-ts.pdf
-
+SRC_DIR := src
+BUILD_DIR := build
+HEADER_SOURCE := $(SRC_DIR)/riscv-server-soc.adoc
+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 \
+           $(XTRA_ADOC_OPTS) \
+		   -D build \
            --failure-level=ERROR
 REQUIRES := --require=asciidoctor-bibtex \
             --require=asciidoctor-diagram \
@@ -42,7 +43,7 @@ REQUIRES := --require=asciidoctor-bibtex \
 
 all: build
 
-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..."; \
@@ -54,18 +55,17 @@ build:
 
 build-container:
 	@echo "Starting build inside Docker container..."
-	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)"
-	$(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(TS_PDF_RESULT) $(TS_HEADER_SOURCE)"
+	$(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) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)
-	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(TS_PDF_RESULT) $(TS_HEADER_SOURCE)
+	$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)
+	$(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $(HEADER_SOURCE)
 	@echo "Build completed successfully."
 
 clean:
 	@echo "Cleaning up generated files..."
-	rm -f $(PDF_RESULT)
-	rm -f $(TS_PDF_RESULT)
+	rm -rf $(BUILD_DIR)
 	@echo "Cleanup completed."

readme.adoc

@@ -3,47 +3,76 @@
 This document is capturing discussions at the Server SoC HW TG.
 This is not an official specification and everything in this document may change.
 
-= License
+== 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). For details, see the link:LICENSE[LICENSE] file.
 
-= Contributors
+== Contributors
 
-Contributors to this specification are contained in the
-https://github.com/riscv-non-isa/riscv-iommu/blob/main/contributors.adoc[contributors.adoc] file.
+The list of contributors to this specification is maintained in the link:src/contributors.adoc[contributors] file.
 
-= Dependencies
+For guidelines on how to contribute, refer to 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.
+== Building the Document
 
-For more information on AsciiDoctor, specification guidelines, or building locally, see the
-https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide].
+=== Directory Structure
 
-= Cloning the project
+The following directories are used to organize the contents of this repo:
 
-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.
+* `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
 
-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:
+=== Prerequisites
 
-    $ 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
+To build the document, you'll need the following tools installed on your system:
 
-= Building the document
+* Make
+* asciidoctor, asciidoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical
+* Docker
 
-The final specification form of PDF can be generated using the `make` command.
+=== Cloning the Repository
+
+```shell
+git clone --recurse-submodules https://github.com/riscv-non-isa/server-soc.git
+```
+
+=== Building the Documentation
+
+To start the build process, run:
+
+```shell
+cd ./server-soc && make build
+```
+
+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
+```
+
+== 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
+----
+
+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
+----

server_soc_header.adoc → src/riscv-server-soc.adoc

@@ -9,13 +9,15 @@
 :preface-title: Preamble
 :colophon:
 :appendix-caption: Appendix
-:imagesdir: images
-:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center]
+// https://docs.asciidoctor.org/asciidoc/latest/macros/images-directory/
+:imagesdir: ../docs-resources/images
+:title-logo-image: image:risc-v_logo.png["RISC-V International Logo",pdfwidth=3.25in,align=center]
 // Settings:
 :experimental:
 :reproducible:
-:imagesoutdir: images
-:bibtex-file: server_soc.bib
+:imagesoutdir: ../build/images
+:srcdir: src
+:bibtex-file: {srcdir}/server_soc.bib
 :bibtex-order: appearance
 :bibtex-style: ieee
 :icons: font
@@ -55,6 +57,7 @@ https://creativecommons.org/licenses/by/4.0/.
 
 Copyright 2022 by RISC-V International.
 
+:imagesdir: images
 [preface]
 include::server_soc_contributors.adoc[]
 include::server_soc_intro.adoc[]