Add landing for GitHub pages, add index to resolved arch

.github/workflows/pages.yml

@@ -43,52 +43,8 @@ jobs:
         run: ./bin/build_container
       - name: Setup project
         run: ./bin/setup
-      - name: Build manual
-        run: ./do gen:html_manual MANUAL_NAME=isa VERSIONS=all
-      - name: Build html documentation for generic_rv64
-        run: ./do gen:html[generic_rv64]
-      - name: Generate YARD docs
-        run: ./do gen:tool_doc
-      - name: Create _site/example_cfg
-        run: mkdir -p _site/example_cfg
-      - name: Create _site/manual
-        run: mkdir -p _site/manual
-      - name: Create _site/pdfs
-        run: mkdir -p _site/pdfs
-      - name: Create _site/htmls
-        run: mkdir -p _site/htmls
-      - name: Copy cfg html
-        run: cp -R gen/cfg_html_doc/generic_rv64/html _site/example_cfg
-      - name: Create RVA20 Profile Release PDF Spec
-        run: ./do gen:profile[RVA20]
-      - name: Copy RVA20 Profile Release PDF
-        run: cp gen/profile_doc/pdf/RVA20.pdf _site/pdfs/RVA20.pdf
-      - name: Create RVA22 Profile Release PDF Spec
-        run: ./do gen:profile[RVA22]
-      - name: Copy RVA22 Profile Release PDF
-        run: cp gen/profile_doc/pdf/RVA22.pdf _site/pdfs/RVA22.pdf
-      - name: Create RVI20 Profile Release PDF Spec
-        run: ./do gen:profile[RVI20]
-      - name: Copy RVI20 Profile Release PDF
-        run: cp gen/profile_doc/pdf/RVA20.pdf _site/pdfs/RVI20.pdf
-      - name: Create MC100-32 PDF Spec
-        run: ./do gen:cert_model_pdf[MC100-32]
-      - name: Copy MC100-32 PDF
-        run: cp gen/certificate_doc/pdf/MC100-32.pdf _site/pdfs/MC100-32.pdf
-      - name: Create MC100-32 HTML Spec
-        run: ./do gen:cert_model_html[MC100-32]
-      - name: Copy MC100-32 HTML
-        run: cp gen/certificate_doc/html/MC100-32.html _site/htmls/MC100-32.html
-      - name: Create MC100-64 PDF Spec
-        run: ./do gen:cert_model_pdf[MC100-64]
-      - name: Copy MC100-64 PDF
-        run: cp gen/certificate_doc/pdf/MC100-64.pdf _site/pdfs/MC100-64.pdf
-      - name: Create MC100-64 HTML Spec
-        run: ./do gen:cert_model_html[MC100-64]
-      - name: Copy MC100-64 HTML
-        run: cp gen/certificate_doc/html/MC100-64.html _site/htmls/MC100-64.html
-      - name: Copy manual html
-        run: cp -R gen/manual/isa/top/all/html _site/manual
+      - name: Create deploy dir
+        run: /bin/bash lib/deploy.sh
       - name: Setup Pages
         uses: actions/configure-pages@v5
       - name: Upload artifact

README.adoc

@@ -2,17 +2,8 @@
 
 == Generated artifacts
 
-The following artifacts have been generated from the top of the `main` branch:
-
-* https://riscv-software-src.github.io/riscv-unified-db/manual/html/index.html[ISA Manual with instruction and CSR appendix]
-* https://riscv-software-src.github.io/riscv-unified-db/example_cfg/html/index.html[configuration-specific documentation]
-* https://riscv-software-src.github.io/riscv-unified-db/ruby/arch_def/index.html[Ruby API documentation (database interface)]
-* https://riscv-software-src.github.io/riscv-unified-db/ruby/idl/index.html[Ruby IDL API documentation (IDL compiler)]
-* https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVI20.pdf[RVI20 Profile Release]
-* https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVA20.pdf[RVA20 Profile Release]
-* https://riscv-software-src.github.io/riscv-unified-db/pdfs/RVA22.pdf[RVA22 Profile Release]
-* https://riscv-software-src.github.io/riscv-unified-db/pdfs/MC100-32.pdf[MC100-32 Certification Requirements Document]
-* https://riscv-software-src.github.io/riscv-unified-db/pdfs/MC100-64.pdf[MC100-64 Certification Requirements Document]
+The latest documentation artifacts generated from the HEAD of main, include ISA manuals, profiles, etc.,
+can be found https://riscv-software-src.github.io/riscv-unified-db/index.html[on the GitHub pages site].
 
 == Overview
 

Rakefile

@@ -48,10 +48,8 @@ namespace :gen do
     end
   end
 
-  desc "Resolve the standard in arch/, and write it to resolved_arch/"
-  task "resolved_arch" do
-    sh "#{$root}/.home/.venv/bin/python3 lib/yaml_resolver.py resolve arch resolved_arch"
-  end
+  desc "Resolve the standard in arch/, and write it to gen/resolved_arch/_"
+  task "resolved_arch" => "#{$root}/.stamps/resolve-_.stamp"
 end
 
 # rule to generate standard for any configurations with an overlay
@@ -121,12 +119,12 @@ namespace :test do
     end
     puts "All instruction encodings pass basic sanity tests"
   end
-  task schema: "gen:resolved_arch" do
+  task schema: "#{$root}/.stamps/resolve-_.stamp" do
     puts "Checking arch files against schema.."
-    Architecture.new("#{$root}/resolved_arch").validate(show_progress: true)
+    Architecture.new("#{$root}/gen/resolved_arch/_").validate(show_progress: true)
     puts "All files validate against their schema"
   end
-  task idl: ["gen:resolved_arch", "#{$root}/.stamps/resolve-rv32.stamp", "#{$root}/.stamps/resolve-rv64.stamp"]  do
+  task idl: ["#{$root}/.stamps/resolve-rv32.stamp", "#{$root}/.stamps/resolve-rv64.stamp"]  do
     print "Parsing IDL code for RV32..."
     cfg_arch32 = cfg_arch_for("rv32")
     puts "done"

bin/setup

@@ -205,14 +205,15 @@ else
     exit 1
 fi
 
-if [ ! -f $ROOT/.git/hooks/pre-commit ]; then
-  cat << HOOK > $ROOT/.git/hooks/pre-commit
+GIT_REPO_ROOT=`git rev-parse --path-format=absolute --git-common-dir | tr -d '\n'`
+if [ ! -f $GIT_REPO_ROOT/hooks/pre-commit ]; then
+  cat << HOOK > $GIT_REPO_ROOT/hooks/pre-commit
 #!/usr/bin/env bash
 # File generated by pre-commit: https://pre-commit.com
 # ID: 138fd403232d2ddd5efb44317e38bf03
 
 # start templated
-INSTALL_PYTHON=$ROOT/bin/python
+INSTALL_PYTHON=\$(realpath ./bin/python)
 ARGS=(hook-impl --config=.pre-commit-config.yaml --hook-type=pre-commit)
 # end templated
 
@@ -228,5 +229,5 @@ else
     exit 1
 fi
 HOOK
-  chmod +x $ROOT/.git/hooks/pre-commit
+  chmod +x $GIT_REPO_ROOT/hooks/pre-commit
 fi

lib/deploy.sh

@@ -0,0 +1,139 @@
+#!/bin/bash
+
+# deploy artifacts to a directory, in preparation for GitHub deployment
+
+ROOT=$(dirname $(dirname $(realpath $BASH_SOURCE[0])))
+
+DEPLOY_DIR="$ROOT/_site"
+PAGES_URL="https://riscv-software-src.github.io/riscv-unified-db"
+
+mkdir -p $DEPLOY_DIR
+
+echo "Create _site/example_cfg"
+mkdir -p $DEPLOY_DIR/example_cfg
+
+echo "Create _site/manual"
+mkdir -p $DEPLOY_DIR/manual
+
+echo "Create _site/pdfs"
+mkdir -p $DEPLOY_DIR/pdfs
+
+
+
+echo "Resolve / Create Index"
+./do gen:resolved_arch
+
+echo "Build manual"
+./do gen:html_manual MANUAL_NAME=isa VERSIONS=all
+
+echo "Copy manual html"
+cp -R gen/manual/isa/top/all/html $DEPLOY_DIR/manual
+
+echo "Build html documentation for generic_rv64"
+./do gen:html[generic_rv64]
+
+echo "Generate YARD docs"
+./do gen:tool_doc
+
+echo "Create _site/htmls"
+mkdir mkdir -p $DEPLOY_DIR/htmls
+
+echo "Copy cfg html"
+cp -R gen/cfg_html_doc/generic_rv64/html $DEPLOY_DIR/example_cfg
+
+echo "Create RVA20 Profile Release PDF Spec"
+./do gen:profile[RVA20]
+
+echo "Copy RVA20 Profile Release PDF"
+cp gen/profile_doc/pdf/RVA20.pdf $DEPLOY_DIR/pdfs/RVA20.pdf
+
+echo "Create RVA22 Profile Release PDF Spec"
+./do gen:profile[RVA22]
+
+echo "Copy RVA22 Profile Release PDF"
+cp gen/profile_doc/pdf/RVA22.pdf $DEPLOY_DIR/pdfs/RVA22.pdf
+
+echo "Create RVI20 Profile Release PDF Spec"
+./do gen:profile[RVI20]
+
+echo "Copy RVI20 Profile Release PDF"
+cp gen/profile_doc/pdf/RVA20.pdf $DEPLOY_DIR/pdfs/RVI20.pdf
+
+echo "Create MC100-32 PDF Spec"
+./do gen:cert_model_pdf[MC100-32]
+
+echo "Copy MC100-32 PDF"
+cp gen/certificate_doc/pdf/MC100-32.pdf $DEPLOY_DIR/pdfs/MC100-32.pdf
+
+echo "Create MC100-32 HTML Spec"
+./do gen:cert_model_html[MC100-32]
+
+echo "Copy MC100-32 HTML"
+cp gen/certificate_doc/html/MC100-32.html $DEPLOY_DIR/htmls/MC100-32.html
+
+echo "Create MC100-64 PDF Spec"
+./do gen:cert_model_pdf[MC100-64]
+
+echo "Copy MC100-64 PDF"
+cp gen/certificate_doc/pdf/MC100-64.pdf $DEPLOY_DIR/pdfs/MC100-64.pdf
+
+echo "Create MC100-64 HTML Spec"
+./do gen:cert_model_html[MC100-64]
+
+echo "Copy MC100-64 HTML"
+cp gen/certificate_doc/html/MC100-64.html $DEPLOY_DIR/htmls/MC100-64.html
+
+echo "Create index"
+cat <<- EOF > $DEPLOY_DIR/index.html
+<!doctype html>
+<html lang="en-us">
+  <head>
+    <title>Release artifacts for $GITHUB_REF_NAME</title>
+  </head>
+  <body>
+    <h1>Release artifacts for <code>riscv-unified-db</code>, ref $GITHUB_REF_NAME</h1>
+    <h2>Commit $GITHUB_SHA</h2>
+    <p>Created on $(date)</p>
+
+    <br/>
+    <h3>Resolved architecture</h3>
+    <ul>
+      <li><a href="$PAGES_URL/resolved_arch/index.yaml">index.yaml</a> Database index, as array of relative paths from $PAGES_URL/resolved_arch</li>
+    </ul>
+
+    <br/>
+    <h3>ISA Manual</h3>
+    <ul>
+      <li><a href="$PAGES_URL/manual/html/index.html">Generated HTML ISA manuals, all versions</a></li>
+    </ul>
+
+    <br/>
+    <h3>Profiles</h3>
+    <ul>
+      <li><a href="$PAGES_URL/pdfs/RVI20.pdf">RVI20</a></li>
+      <li><a href="$PAGES_URL/pdfs/RVA20.pdf">RVA20</a></li>
+      <li><a href="$PAGES_URL/pdfs/RVA22.pdf">RVA22</a></li>
+    </ul>
+
+    <br/>
+    <h3>Certification Requirements Documents</h3>
+    <ul>
+      <li><a href="$PAGES_URL/pdfs/MC100-32.pdf">MC100-32</a></li>
+      <li><a href="$PAGES_URL/pdfs/MC100-64.pdf">MC100-64</a></li>
+    </ul>
+
+    <br/>
+    <h3>Configuration-specific documentation</h3>
+    <ul>
+      <li><a href="$PAGES_URL/example_cfg/html/index.html">Architecture documentation for example RV64 config</a></li>
+    </ul>
+
+    <br/>
+    <h3>UDB Tool Documentation</h3>
+    <ul>
+      <li><a href="$PAGES_URL/ruby/idl/index.html">IDL language documentation</a></li>
+      <li><a href="$PAGES_URL/ruby/arch_def/index.html">Ruby UDB interface documentation</a></li>
+    </ul>
+  </body>
+</html>
+EOF

lib/yaml_resolver.py

@@ -167,6 +167,20 @@ def write_yaml(file_path: str | Path, data):
         yaml.dump(data, file)
 
 
+def write_json(file_path: str | Path, data):
+    """Write data as JSON to file_path
+
+    Parameters
+    ----------
+    file_path : str, Path
+      Filesystem path to the JSON file
+    data : dict, list
+      The object to write as JSON
+    """
+    with open(file_path, "w") as file:
+        json.dump(data, file)
+
+
 def dig(obj: dict, *keys):
     """Digs data out of dictionary obj
 
@@ -597,15 +611,20 @@ def resolve_file(
             if args.no_progress
             else tqdm(arch_paths, ascii=True, desc="Resolving arch")
         )
+        abs_resolved_dir = (
+            f"{UDB_ROOT}/{args.resolved_dir}"
+            if not os.path.isabs(args.resolved_dir)
+            else f"{args.resolved_dir}"
+        )
         for arch_path in iter:
-            resolved_arch_path = (
-                f"{UDB_ROOT}/{args.resolved_dir}/{arch_path}"
-                if not os.path.isabs(args.resolved_dir)
-                else f"{args.resolved_dir}/{arch_path}"
-            )
+            resolved_arch_path = f"{abs_resolved_dir}/{arch_path}"
             os.makedirs(os.path.dirname(resolved_arch_path), exist_ok=True)
             resolve_file(
                 arch_path, args.arch_dir, args.resolved_dir, not args.no_checks
             )
 
+        # create index
+        write_yaml(f"{abs_resolved_dir}/index.yaml", arch_paths)
+        write_json(f"{abs_resolved_dir}/index.json", arch_paths)
+
         print(f"[INFO] Resolved architecture files written to {args.resolved_dir}")