docs: generate_summary

OpenXiangShan · Dec 20, 2024 · a5fc840 · a5fc840
1 parent 8f4c8e1
commit a5fc840
Show file tree

Hide file tree

Showing 27 changed files with 57 additions and 41 deletions.
diff --git a/.gitignore b/.gitignore
@@ -11,4 +11,5 @@ book
 *_py.dot
 *_py.svg
 __pycache__
-*extract.md
+*.mkd
+docs/SUMMARY.md
diff --git a/Makefile b/Makefile
@@ -1,17 +1,21 @@
 .NOTINTERMEDIATE:
 
 PYSVGs=$(subst _dot.py,_py.svg,$(shell find docs/ -name "*_dot.py"))
-EXTRACTMDs=docs/reference/default_extract.md
-doc: $(shell find . -name "*.md") ${PYSVGs} ${EXTRACTMDs}
+EXTRACTMKDs=docs/references/default_extract.mkd
+MDs=$(shell find . -name "*.md")
+doc: ${MDs} docs/SUMMARY.md ${PYSVGs} ${EXTRACTMKDs}
 	mdbook build
 
-%_py.dot: %_dot.py docs/designs/builders/images/common.py
+docs/SUMMARY.md: ./docs/generate_summary.py $(filter-out %SUMMARY.md,${MDs})
+	$< $(dir $<) > $@
+
+%_py.dot: %_dot.py docs/designs/4.builders/images/common.py
 	python3 $<
 %.svg: %.dot
 	dot -Tsvg $< -o $@
 	# css can only recognize intrinsic size in px
 	# https://developer.mozilla.org/en-US/docs/Glossary/Intrinsic_Size
 	sed -i 's/\([0-9]\+\)pt/\1px/g' $@
 
-docs/reference/default_extract.md: ./docs/extract_comments.py default.nix
+docs/references/default_extract.mkd: ./docs/extract_comments.py default.nix
 	$^ $@
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
diff --git a/docs/designs/overview.md → docs/designs/1.overview.md b/docs/designs/overview.md → docs/designs/1.overview.md
diff --git a/docs/designs/configuration_system.md → docs/designs/2.configuration_system.md b/docs/designs/configuration_system.md → docs/designs/2.configuration_system.md
diff --git a/docs/designs/benchmarks/index.md → docs/designs/3.benchmarks/index.md b/docs/designs/benchmarks/index.md → docs/designs/3.benchmarks/index.md
diff --git a/docs/designs/benchmarks/openblas.md → docs/designs/3.benchmarks/openblas.md b/docs/designs/benchmarks/openblas.md → docs/designs/3.benchmarks/openblas.md
diff --git a/docs/designs/benchmarks/spec2006.md → docs/designs/3.benchmarks/spec2006.md b/docs/designs/benchmarks/spec2006.md → docs/designs/3.benchmarks/spec2006.md
@@ -1,4 +1,4 @@
-TODO:
+# SPEC CPU 2006
 
 ## Preparing SPEC CPU2006 Source Code
 

diff --git a/docs/designs/builders/imgBuilder.md → docs/designs/4.builders/1.imgBuilder.md b/docs/designs/builders/imgBuilder.md → docs/designs/4.builders/1.imgBuilder.md
diff --git a/docs/designs/builders/cptBuilder.md → docs/designs/4.builders/2.cptBuilder.md b/docs/designs/builders/cptBuilder.md → docs/designs/4.builders/2.cptBuilder.md
diff --git a/docs/designs/builders/images/common.py → docs/designs/4.builders/images/common.py b/docs/designs/builders/images/common.py → docs/designs/4.builders/images/common.py
diff --git a/docs/designs/builders/images/deps_dot.py → docs/designs/4.builders/images/deps_dot.py b/docs/designs/builders/images/deps_dot.py → docs/designs/4.builders/images/deps_dot.py
diff --git a/docs/designs/builders/images/overview_dot.py → ...designs/4.builders/images/overview_dot.py b/docs/designs/builders/images/overview_dot.py → ...designs/4.builders/images/overview_dot.py
diff --git a/docs/designs/builders/index.md → docs/designs/4.builders/index.md b/docs/designs/builders/index.md → docs/designs/4.builders/index.md
diff --git a/docs/designs/outputs/gen_table.js → docs/designs/5.outputs/gen_table.js b/docs/designs/outputs/gen_table.js → docs/designs/5.outputs/gen_table.js
diff --git a/docs/designs/outputs/index.md → docs/designs/5.outputs/index.md b/docs/designs/outputs/index.md → docs/designs/5.outputs/index.md
diff --git a/docs/generate_summary.py b/docs/generate_summary.py
@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+import glob, re, sys
+
+if len(sys.argv) < 2:
+  print(f"Usage: {sys.argv[0]} <docs_dir>")
+  sys.exit(1)
+
+def generate_section_body(root_dir:str, sub_dir:str) -> list[str]:
+  mds_path = glob.glob(f"{sub_dir}/**/*.md", root_dir=root_dir, recursive=True)
+  mds_path = sorted(mds_path, key=lambda path: path.rstrip("index.md"))
+  entries: list[str] = []
+  levels: list[int] = []
+  for md_path in mds_path:
+    level = md_path.count('/')
+    if md_path.endswith("index.md"):
+      level -= 1
+    title: str
+    with open(f"{root_dir}/{md_path}", 'r') as f: title = (re.findall("^# (.*)", f.readline())+[""])[0]
+    entries.append(f"{'  '*level}* [{title}]({md_path})")
+    levels.append(level)
+  min_level = min(levels)
+  well_indented_entries = [entry[2*min_level:] for entry in entries]
+  return well_indented_entries
+
+print("# Summary")
+print("")
+print("# 入门（Get Started）")
+print("")
+print("* [🏠README.md](./index.md)")
+print("")
+print("# 使用（Usages）")
+print("")
+for line in generate_section_body(sys.argv[1], "usages/"):
+  print(line)
+print("")
+print("# 设计（Designs）")
+print("")
+for line in generate_section_body(sys.argv[1], "designs/"):
+  print(line)
+print("")
+print("# 参考（References）")
+print("")
+for line in generate_section_body(sys.argv[1], "references/"):
+  print(line)
diff --git a/docs/reference/configurable.md → docs/references/1.configurable.md b/docs/reference/configurable.md → docs/references/1.configurable.md
@@ -1,3 +1,3 @@
 # 🧾可配参数（Configurable Arguments）
 
-{{ #include ./default_extract.md }}
+{{ #include ./default_extract.mkd }}
diff --git a/docs/reference/benchmarks_scope.md → docs/references/2.benchmarks_scope.md b/docs/reference/benchmarks_scope.md → docs/references/2.benchmarks_scope.md
diff --git a/docs/reference/builders_scope.md → docs/references/3.builders_scope.md b/docs/reference/builders_scope.md → docs/references/3.builders_scope.md
diff --git a/docs/usages/building_outputs.md → docs/usages/1.building_outputs.md b/docs/usages/building_outputs.md → docs/usages/1.building_outputs.md
diff --git a/docs/usages/configuring.md → docs/usages/2.configuring.md b/docs/usages/configuring.md → docs/usages/2.configuring.md
diff --git a/docs/usages/examples.md → docs/usages/3.examples.md b/docs/usages/examples.md → docs/usages/3.examples.md
diff --git a/docs/usages/running/emulators.md → docs/usages/4.running/emulators.md b/docs/usages/running/emulators.md → docs/usages/4.running/emulators.md
diff --git a/docs/usages/running/gem5.md → docs/usages/4.running/gem5.md b/docs/usages/running/gem5.md → docs/usages/4.running/gem5.md
@@ -1,4 +1,4 @@
-## Running on Gem5
+# Running on Gem5
 
 The checkpoints generated by this repository can be run on Gem5, Nemu, and XiangShan RTL in the XiangShan repository. Here we explain the considerations for running on Gem5.
 

diff --git a/docs/usages/running/index.md → docs/usages/4.running/index.md b/docs/usages/running/index.md → docs/usages/4.running/index.md
diff --git a/docs/usages/running/nemu.md → docs/usages/4.running/nemu.md b/docs/usages/running/nemu.md → docs/usages/4.running/nemu.md