Skip to content

Commit 0368d16

Browse files
dhower-qcdhower-qc
authored
Add landing for GitHub pages, add index to resolved arch (#459)
* Add landing for GitHub pages, add index to resolved arch * Create JSON index with resolved arch * Move some commands in deploy.sh
1 parent b9f04cd commit 0368d16

File tree

6 files changed

+177
-73
lines changed

6 files changed

+177
-73
lines changed

‎.github/workflows/pages.yml‎

Lines changed: 2 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -43,52 +43,8 @@ jobs:
4343
run: ./bin/build_container
4444
- name: Setup project
4545
run: ./bin/setup
46-
- name: Build manual
47-
run: ./do gen:html_manual MANUAL_NAME=isa VERSIONS=all
48-
- name: Build html documentation for generic_rv64
49-
run: ./do gen:html[generic_rv64]
50-
- name: Generate YARD docs
51-
run: ./do gen:tool_doc
52-
- name: Create _site/example_cfg
53-
run: mkdir -p _site/example_cfg
54-
- name: Create _site/manual
55-
run: mkdir -p _site/manual
56-
- name: Create _site/pdfs
57-
run: mkdir -p _site/pdfs
58-
- name: Create _site/htmls
59-
run: mkdir -p _site/htmls
60-
- name: Copy cfg html
61-
run: cp -R gen/cfg_html_doc/generic_rv64/html _site/example_cfg
62-
- name: Create RVA20 Profile Release PDF Spec
63-
run: ./do gen:profile[RVA20]
64-
- name: Copy RVA20 Profile Release PDF
65-
run: cp gen/profile_doc/pdf/RVA20.pdf _site/pdfs/RVA20.pdf
66-
- name: Create RVA22 Profile Release PDF Spec
67-
run: ./do gen:profile[RVA22]
68-
- name: Copy RVA22 Profile Release PDF
69-
run: cp gen/profile_doc/pdf/RVA22.pdf _site/pdfs/RVA22.pdf
70-
- name: Create RVI20 Profile Release PDF Spec
71-
run: ./do gen:profile[RVI20]
72-
- name: Copy RVI20 Profile Release PDF
73-
run: cp gen/profile_doc/pdf/RVA20.pdf _site/pdfs/RVI20.pdf
74-
- name: Create MC100-32 PDF Spec
75-
run: ./do gen:cert_model_pdf[MC100-32]
76-
- name: Copy MC100-32 PDF
77-
run: cp gen/certificate_doc/pdf/MC100-32.pdf _site/pdfs/MC100-32.pdf
78-
- name: Create MC100-32 HTML Spec
79-
run: ./do gen:cert_model_html[MC100-32]
80-
- name: Copy MC100-32 HTML
81-
run: cp gen/certificate_doc/html/MC100-32.html _site/htmls/MC100-32.html
82-
- name: Create MC100-64 PDF Spec
83-
run: ./do gen:cert_model_pdf[MC100-64]
84-
- name: Copy MC100-64 PDF
85-
run: cp gen/certificate_doc/pdf/MC100-64.pdf _site/pdfs/MC100-64.pdf
86-
- name: Create MC100-64 HTML Spec
87-
run: ./do gen:cert_model_html[MC100-64]
88-
- name: Copy MC100-64 HTML
89-
run: cp gen/certificate_doc/html/MC100-64.html _site/htmls/MC100-64.html
90-
- name: Copy manual html
91-
run: cp -R gen/manual/isa/top/all/html _site/manual
46+
- name: Create deploy dir
47+
run: /bin/bash lib/deploy.sh
9248
- name: Setup Pages
9349
uses: actions/configure-pages@v5
9450
- name: Upload artifact

‎README.adoc‎

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,17 +2,8 @@
22

33
== Generated artifacts
44

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

178
== Overview
189

‎Rakefile‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,8 @@ namespace :gen do
4848
end
4949
end
5050

51-
desc "Resolve the standard in arch/, and write it to resolved_arch/"
52-
task "resolved_arch" do
53-
sh "#{$root}/.home/.venv/bin/python3 lib/yaml_resolver.py resolve arch resolved_arch"
54-
end
51+
desc "Resolve the standard in arch/, and write it to gen/resolved_arch/_"
52+
task "resolved_arch" => "#{$root}/.stamps/resolve-_.stamp"
5553
end
5654

5755
# rule to generate standard for any configurations with an overlay
@@ -127,12 +125,12 @@ namespace :test do
127125
end
128126
puts "All instruction encodings pass basic sanity tests"
129127
end
130-
task schema: "gen:resolved_arch" do
128+
task schema: "#{$root}/.stamps/resolve-_.stamp" do
131129
puts "Checking arch files against schema.."
132-
Architecture.new("#{$root}/resolved_arch").validate(show_progress: true)
130+
Architecture.new("#{$root}/gen/resolved_arch/_").validate(show_progress: true)
133131
puts "All files validate against their schema"
134132
end
135-
task idl: ["gen:resolved_arch", "#{$root}/.stamps/resolve-rv32.stamp", "#{$root}/.stamps/resolve-rv64.stamp"] do
133+
task idl: ["#{$root}/.stamps/resolve-rv32.stamp", "#{$root}/.stamps/resolve-rv64.stamp"] do
136134
print "Parsing IDL code for RV32..."
137135
cfg_arch32 = cfg_arch_for("rv32")
138136
puts "done"

‎bin/setup‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -205,14 +205,15 @@ else
205205
exit 1
206206
fi
207207

208-
if [ ! -f $ROOT/.git/hooks/pre-commit ]; then
209-
cat << HOOK > $ROOT/.git/hooks/pre-commit
208+
GIT_REPO_ROOT=`git rev-parse --path-format=absolute --git-common-dir | tr -d '\n'`
209+
if [ ! -f $GIT_REPO_ROOT/hooks/pre-commit ]; then
210+
cat << HOOK > $GIT_REPO_ROOT/hooks/pre-commit
210211
#!/usr/bin/env bash
211212
# File generated by pre-commit: https://pre-commit.com
212213
# ID: 138fd403232d2ddd5efb44317e38bf03
213214
214215
# start templated
215-
INSTALL_PYTHON=$ROOT/bin/python
216+
INSTALL_PYTHON=\$(realpath ./bin/python)
216217
ARGS=(hook-impl --config=.pre-commit-config.yaml --hook-type=pre-commit)
217218
# end templated
218219
@@ -228,5 +229,5 @@ else
228229
exit 1
229230
fi
230231
HOOK
231-
chmod +x $ROOT/.git/hooks/pre-commit
232+
chmod +x $GIT_REPO_ROOT/hooks/pre-commit
232233
fi

‎lib/deploy.sh‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
#!/bin/bash
2+
3+
# deploy artifacts to a directory, in preparation for GitHub deployment
4+
5+
ROOT=$(dirname $(dirname $(realpath $BASH_SOURCE[0])))
6+
7+
DEPLOY_DIR="$ROOT/_site"
8+
PAGES_URL="https://riscv-software-src.github.io/riscv-unified-db"
9+
10+
mkdir -p $DEPLOY_DIR
11+
12+
echo "Create _site/example_cfg"
13+
mkdir -p $DEPLOY_DIR/example_cfg
14+
15+
echo "Create _site/manual"
16+
mkdir -p $DEPLOY_DIR/manual
17+
18+
echo "Create _site/pdfs"
19+
mkdir -p $DEPLOY_DIR/pdfs
20+
21+
22+
23+
echo "Resolve / Create Index"
24+
./do gen:resolved_arch
25+
26+
echo "Build manual"
27+
./do gen:html_manual MANUAL_NAME=isa VERSIONS=all
28+
29+
echo "Copy manual html"
30+
cp -R gen/manual/isa/top/all/html $DEPLOY_DIR/manual
31+
32+
echo "Build html documentation for generic_rv64"
33+
./do gen:html[generic_rv64]
34+
35+
echo "Generate YARD docs"
36+
./do gen:tool_doc
37+
38+
echo "Create _site/htmls"
39+
mkdir mkdir -p $DEPLOY_DIR/htmls
40+
41+
echo "Copy cfg html"
42+
cp -R gen/cfg_html_doc/generic_rv64/html $DEPLOY_DIR/example_cfg
43+
44+
echo "Create RVA20 Profile Release PDF Spec"
45+
./do gen:profile[RVA20]
46+
47+
echo "Copy RVA20 Profile Release PDF"
48+
cp gen/profile_doc/pdf/RVA20.pdf $DEPLOY_DIR/pdfs/RVA20.pdf
49+
50+
echo "Create RVA22 Profile Release PDF Spec"
51+
./do gen:profile[RVA22]
52+
53+
echo "Copy RVA22 Profile Release PDF"
54+
cp gen/profile_doc/pdf/RVA22.pdf $DEPLOY_DIR/pdfs/RVA22.pdf
55+
56+
echo "Create RVI20 Profile Release PDF Spec"
57+
./do gen:profile[RVI20]
58+
59+
echo "Copy RVI20 Profile Release PDF"
60+
cp gen/profile_doc/pdf/RVA20.pdf $DEPLOY_DIR/pdfs/RVI20.pdf
61+
62+
echo "Create MC100-32 PDF Spec"
63+
./do gen:cert_model_pdf[MC100-32]
64+
65+
echo "Copy MC100-32 PDF"
66+
cp gen/certificate_doc/pdf/MC100-32.pdf $DEPLOY_DIR/pdfs/MC100-32.pdf
67+
68+
echo "Create MC100-32 HTML Spec"
69+
./do gen:cert_model_html[MC100-32]
70+
71+
echo "Copy MC100-32 HTML"
72+
cp gen/certificate_doc/html/MC100-32.html $DEPLOY_DIR/htmls/MC100-32.html
73+
74+
echo "Create MC100-64 PDF Spec"
75+
./do gen:cert_model_pdf[MC100-64]
76+
77+
echo "Copy MC100-64 PDF"
78+
cp gen/certificate_doc/pdf/MC100-64.pdf $DEPLOY_DIR/pdfs/MC100-64.pdf
79+
80+
echo "Create MC100-64 HTML Spec"
81+
./do gen:cert_model_html[MC100-64]
82+
83+
echo "Copy MC100-64 HTML"
84+
cp gen/certificate_doc/html/MC100-64.html $DEPLOY_DIR/htmls/MC100-64.html
85+
86+
echo "Create index"
87+
cat <<- EOF > $DEPLOY_DIR/index.html
88+
<!doctype html>
89+
<html lang="en-us">
90+
<head>
91+
<title>Release artifacts for $GITHUB_REF_NAME</title>
92+
</head>
93+
<body>
94+
<h1>Release artifacts for <code>riscv-unified-db</code>, ref $GITHUB_REF_NAME</h1>
95+
<h2>Commit $GITHUB_SHA</h2>
96+
<p>Created on $(date)</p>
97+
98+
<br/>
99+
<h3>Resolved architecture</h3>
100+
<ul>
101+
<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>
102+
</ul>
103+
104+
<br/>
105+
<h3>ISA Manual</h3>
106+
<ul>
107+
<li><a href="$PAGES_URL/manual/html/index.html">Generated HTML ISA manuals, all versions</a></li>
108+
</ul>
109+
110+
<br/>
111+
<h3>Profiles</h3>
112+
<ul>
113+
<li><a href="$PAGES_URL/pdfs/RVI20.pdf">RVI20</a></li>
114+
<li><a href="$PAGES_URL/pdfs/RVA20.pdf">RVA20</a></li>
115+
<li><a href="$PAGES_URL/pdfs/RVA22.pdf">RVA22</a></li>
116+
</ul>
117+
118+
<br/>
119+
<h3>Certification Requirements Documents</h3>
120+
<ul>
121+
<li><a href="$PAGES_URL/pdfs/MC100-32.pdf">MC100-32</a></li>
122+
<li><a href="$PAGES_URL/pdfs/MC100-64.pdf">MC100-64</a></li>
123+
</ul>
124+
125+
<br/>
126+
<h3>Configuration-specific documentation</h3>
127+
<ul>
128+
<li><a href="$PAGES_URL/example_cfg/html/index.html">Architecture documentation for example RV64 config</a></li>
129+
</ul>
130+
131+
<br/>
132+
<h3>UDB Tool Documentation</h3>
133+
<ul>
134+
<li><a href="$PAGES_URL/ruby/idl/index.html">IDL language documentation</a></li>
135+
<li><a href="$PAGES_URL/ruby/arch_def/index.html">Ruby UDB interface documentation</a></li>
136+
</ul>
137+
</body>
138+
</html>
139+
EOF

‎lib/yaml_resolver.py‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,20 @@ def write_yaml(file_path: str | Path, data):
167167
yaml.dump(data, file)
168168

169169

170+
def write_json(file_path: str | Path, data):
171+
"""Write data as JSON to file_path
172+
173+
Parameters
174+
----------
175+
file_path : str, Path
176+
Filesystem path to the JSON file
177+
data : dict, list
178+
The object to write as JSON
179+
"""
180+
with open(file_path, "w") as file:
181+
json.dump(data, file)
182+
183+
170184
def dig(obj: dict, *keys):
171185
"""Digs data out of dictionary obj
172186
@@ -597,15 +611,20 @@ def resolve_file(
597611
if args.no_progress
598612
else tqdm(arch_paths, ascii=True, desc="Resolving arch")
599613
)
614+
abs_resolved_dir = (
615+
f"{UDB_ROOT}/{args.resolved_dir}"
616+
if not os.path.isabs(args.resolved_dir)
617+
else f"{args.resolved_dir}"
618+
)
600619
for arch_path in iter:
601-
resolved_arch_path = (
602-
f"{UDB_ROOT}/{args.resolved_dir}/{arch_path}"
603-
if not os.path.isabs(args.resolved_dir)
604-
else f"{args.resolved_dir}/{arch_path}"
605-
)
620+
resolved_arch_path = f"{abs_resolved_dir}/{arch_path}"
606621
os.makedirs(os.path.dirname(resolved_arch_path), exist_ok=True)
607622
resolve_file(
608623
arch_path, args.arch_dir, args.resolved_dir, not args.no_checks
609624
)
610625

626+
# create index
627+
write_yaml(f"{abs_resolved_dir}/index.yaml", arch_paths)
628+
write_json(f"{abs_resolved_dir}/index.json", arch_paths)
629+
611630
print(f"[INFO] Resolved architecture files written to {args.resolved_dir}")

0 commit comments

Comments
 (0)