From b7944727ff2ae0d3cdff88c18252ad46c9aeecff Mon Sep 17 00:00:00 2001 From: Derek Hower Date: Tue, 11 Feb 2025 08:03:23 -0800 Subject: [PATCH 1/3] Add landing for GitHub pages, add index to resolved arch --- .github/workflows/pages.yml | 48 +------------ README.adoc | 13 +--- Rakefile | 12 ++-- bin/setup | 9 +-- lib/deploy.sh | 137 ++++++++++++++++++++++++++++++++++++ lib/yaml_resolver.py | 14 ++-- 6 files changed, 160 insertions(+), 73 deletions(-) create mode 100644 lib/deploy.sh diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml index 4060bfaf1..2f8b77ec6 100644 --- a/.github/workflows/pages.yml +++ b/.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 diff --git a/README.adoc b/README.adoc index bca01db3b..30f7d8668 100644 --- a/README.adoc +++ b/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 diff --git a/Rakefile b/Rakefile index 40b2c220e..5e4d62a0f 100644 --- a/Rakefile +++ b/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" diff --git a/bin/setup b/bin/setup index 0f89e8b74..c5e8abf8d 100755 --- a/bin/setup +++ b/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 diff --git a/lib/deploy.sh b/lib/deploy.sh new file mode 100644 index 000000000..64d76e745 --- /dev/null +++ b/lib/deploy.sh @@ -0,0 +1,137 @@ +#!/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 "Resolve / Create Index" +./do gen:resolved_arch + +echo "Build manual" +./do gen:html_manual MANUAL_NAME=isa VERSIONS=all + +echo "Build html documentation for generic_rv64" +./do gen:html[generic_rv64] + +echo "Generate YARD docs" +./do gen:tool_doc + +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 "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" +cp ./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 "Copy manual html" +cp -R gen/manual/isa/top/all/html $DEPLOY_DIR/manual + +echo "Create index" +cat <<- EOF > $DEPLOY_DIR/index.html + + + + Release artifacts for $GITHUB_REF_NAME + + +

Release artifacts for riscv-unified-db, ref $GITHUB_REF_NAME

+

Commit $GITHUB_SHA

+

Created on $(date)

+ +
+

Resolved architecture

+ + +
+

ISA Manual

+ + +
+

Profiles

+ + +
+

Certification Requirements Documents

+ + +
+

Configuration-specific documentation

+ + +
+

UDB Tool Documentation

+ + + +EOF diff --git a/lib/yaml_resolver.py b/lib/yaml_resolver.py index 110c271bf..d574c4890 100644 --- a/lib/yaml_resolver.py +++ b/lib/yaml_resolver.py @@ -597,15 +597,19 @@ 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) + print(f"[INFO] Resolved architecture files written to {args.resolved_dir}") From 277ed2cf16eb98e76758c197bae5918a411792ab Mon Sep 17 00:00:00 2001 From: Derek Hower Date: Tue, 11 Feb 2025 08:18:00 -0800 Subject: [PATCH 2/3] Create JSON index with resolved arch --- lib/yaml_resolver.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/lib/yaml_resolver.py b/lib/yaml_resolver.py index d574c4890..04c35eee1 100644 --- a/lib/yaml_resolver.py +++ b/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 @@ -611,5 +625,6 @@ def resolve_file( # 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}") From 5c96cf63a7503ab8cb2b2013cbe7a4f3d269faf0 Mon Sep 17 00:00:00 2001 From: Derek Hower Date: Tue, 11 Feb 2025 08:36:09 -0800 Subject: [PATCH 3/3] Move some commands in deploy.sh --- lib/deploy.sh | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/lib/deploy.sh b/lib/deploy.sh index 64d76e745..f5c80c79f 100644 --- a/lib/deploy.sh +++ b/lib/deploy.sh @@ -9,27 +9,32 @@ 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/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 "Create _site/htmls" mkdir mkdir -p $DEPLOY_DIR/htmls @@ -61,7 +66,7 @@ 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" -cp ./do gen:cert_model_html[MC100-32] +./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 @@ -78,9 +83,6 @@ echo "Create MC100-64 HTML Spec" echo "Copy MC100-64 HTML" cp gen/certificate_doc/html/MC100-64.html $DEPLOY_DIR/htmls/MC100-64.html -echo "Copy manual html" -cp -R gen/manual/isa/top/all/html $DEPLOY_DIR/manual - echo "Create index" cat <<- EOF > $DEPLOY_DIR/index.html