From a5fc8403664f3b5fd4f6b8b5dc9c60afde7f4df1 Mon Sep 17 00:00:00 2001 From: xieby1 Date: Fri, 20 Dec 2024 17:38:27 +0800 Subject: [PATCH] docs: generate_summary --- .gitignore | 3 +- Makefile | 12 +++-- docs/SUMMARY.md | 33 -------------- docs/designs/{overview.md => 1.overview.md} | 0 ...on_system.md => 2.configuration_system.md} | 0 .../{benchmarks => 3.benchmarks}/index.md | 0 .../{benchmarks => 3.benchmarks}/openblas.md | 0 .../{benchmarks => 3.benchmarks}/spec2006.md | 2 +- .../1.imgBuilder.md} | 0 .../2.cptBuilder.md} | 0 .../{builders => 4.builders}/images/common.py | 0 .../images/deps_dot.py | 0 .../images/overview_dot.py | 0 .../designs/{builders => 4.builders}/index.md | 0 .../{outputs => 5.outputs}/gen_table.js | 0 docs/designs/{outputs => 5.outputs}/index.md | 0 docs/generate_summary.py | 44 +++++++++++++++++++ .../1.configurable.md} | 2 +- .../2.benchmarks_scope.md} | 0 .../3.builders_scope.md} | 0 ...lding_outputs.md => 1.building_outputs.md} | 0 .../{configuring.md => 2.configuring.md} | 0 docs/usages/{examples.md => 3.examples.md} | 0 .../{running => 4.running}/emulators.md | 0 docs/usages/{running => 4.running}/gem5.md | 2 +- docs/usages/{running => 4.running}/index.md | 0 docs/usages/{running => 4.running}/nemu.md | 0 27 files changed, 57 insertions(+), 41 deletions(-) delete mode 100644 docs/SUMMARY.md rename docs/designs/{overview.md => 1.overview.md} (100%) rename docs/designs/{configuration_system.md => 2.configuration_system.md} (100%) rename docs/designs/{benchmarks => 3.benchmarks}/index.md (100%) rename docs/designs/{benchmarks => 3.benchmarks}/openblas.md (100%) rename docs/designs/{benchmarks => 3.benchmarks}/spec2006.md (99%) rename docs/designs/{builders/imgBuilder.md => 4.builders/1.imgBuilder.md} (100%) rename docs/designs/{builders/cptBuilder.md => 4.builders/2.cptBuilder.md} (100%) rename docs/designs/{builders => 4.builders}/images/common.py (100%) rename docs/designs/{builders => 4.builders}/images/deps_dot.py (100%) rename docs/designs/{builders => 4.builders}/images/overview_dot.py (100%) rename docs/designs/{builders => 4.builders}/index.md (100%) rename docs/designs/{outputs => 5.outputs}/gen_table.js (100%) rename docs/designs/{outputs => 5.outputs}/index.md (100%) create mode 100755 docs/generate_summary.py rename docs/{reference/configurable.md => references/1.configurable.md} (56%) rename docs/{reference/benchmarks_scope.md => references/2.benchmarks_scope.md} (100%) rename docs/{reference/builders_scope.md => references/3.builders_scope.md} (100%) rename docs/usages/{building_outputs.md => 1.building_outputs.md} (100%) rename docs/usages/{configuring.md => 2.configuring.md} (100%) rename docs/usages/{examples.md => 3.examples.md} (100%) rename docs/usages/{running => 4.running}/emulators.md (100%) rename docs/usages/{running => 4.running}/gem5.md (99%) rename docs/usages/{running => 4.running}/index.md (100%) rename docs/usages/{running => 4.running}/nemu.md (100%) diff --git a/.gitignore b/.gitignore index 5f7bc32..76a62e0 100644 --- 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 index aba0531..f6aa6ea 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,15 @@ .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 $@ @@ -13,5 +17,5 @@ doc: $(shell find . -name "*.md") ${PYSVGs} ${EXTRACTMDs} # 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 deleted file mode 100644 index 28f2d02..0000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,33 +0,0 @@ -# Summary - -# 入门（Get Started） - -* [🏠README.md](./index.md) - -# 使用（Usages） - -* [🔨构建各类输出（Building Various Outputs）](./usages/building_outputs.md) -* [🧾配参数（Configuring Arguments）](./usages/configuring.md) - * [🎮例子（Examples）](./usages/examples.md) -* [💽运行输出的镜像（Running Output Images）](./usages/running/index.md) - * [仿真器（Emulators）](./usages/running/emulators.md) - * [GEM5](./usages/running/gem5.md) - * [NEMU](./usages/running/nemu.md) - -# 设计（Designs） - -* [🌏概览（Overview）](./designs/overview.md) -* [🧾配置系统（Configuration System）](./designs/configuration_system.md) -* [📈基准测试（Benchmarks）](./designs/benchmarks/index.md) - * [OpenBLAS](./designs/benchmarks/openblas.md) - * [SPEC CPU 2006](./designs/benchmarks/spec2006.md) -* [🔨构建器（Builders）](./designs/builders/index.md) - * [镜像构建器（Image Builder）](./designs/builders/imgBuilder.md) - * [切片构建器（Checkpoint Builder）](./designs/builders/cptBuilder.md) -* [📊输出（Outputs）](./designs/outputs/index.md) - -# 参考（References） - -* [🧾可配参数（Configurable Arguments）](./reference/configurable.md) -* [📈基准测试围（Benchmarks Scope）](./reference/benchmarks_scope.md) -* [🔨构建器围（Builders Scope）](./reference/builders_scope.md) diff --git a/docs/designs/overview.md b/docs/designs/1.overview.md similarity index 100% rename from docs/designs/overview.md rename to docs/designs/1.overview.md diff --git a/docs/designs/configuration_system.md b/docs/designs/2.configuration_system.md similarity index 100% rename from docs/designs/configuration_system.md rename to docs/designs/2.configuration_system.md diff --git a/docs/designs/benchmarks/index.md b/docs/designs/3.benchmarks/index.md similarity index 100% rename from docs/designs/benchmarks/index.md rename to docs/designs/3.benchmarks/index.md diff --git a/docs/designs/benchmarks/openblas.md b/docs/designs/3.benchmarks/openblas.md similarity index 100% rename from docs/designs/benchmarks/openblas.md rename to docs/designs/3.benchmarks/openblas.md diff --git a/docs/designs/benchmarks/spec2006.md b/docs/designs/3.benchmarks/spec2006.md similarity index 99% rename from docs/designs/benchmarks/spec2006.md rename to docs/designs/3.benchmarks/spec2006.md index 275152a..1c02e3f 100644 --- a/docs/designs/benchmarks/spec2006.md +++ b/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 b/docs/designs/4.builders/1.imgBuilder.md similarity index 100% rename from docs/designs/builders/imgBuilder.md rename to docs/designs/4.builders/1.imgBuilder.md diff --git a/docs/designs/builders/cptBuilder.md b/docs/designs/4.builders/2.cptBuilder.md similarity index 100% rename from docs/designs/builders/cptBuilder.md rename to docs/designs/4.builders/2.cptBuilder.md diff --git a/docs/designs/builders/images/common.py b/docs/designs/4.builders/images/common.py similarity index 100% rename from docs/designs/builders/images/common.py rename to docs/designs/4.builders/images/common.py diff --git a/docs/designs/builders/images/deps_dot.py b/docs/designs/4.builders/images/deps_dot.py similarity index 100% rename from docs/designs/builders/images/deps_dot.py rename to docs/designs/4.builders/images/deps_dot.py diff --git a/docs/designs/builders/images/overview_dot.py b/docs/designs/4.builders/images/overview_dot.py similarity index 100% rename from docs/designs/builders/images/overview_dot.py rename to docs/designs/4.builders/images/overview_dot.py diff --git a/docs/designs/builders/index.md b/docs/designs/4.builders/index.md similarity index 100% rename from docs/designs/builders/index.md rename to docs/designs/4.builders/index.md diff --git a/docs/designs/outputs/gen_table.js b/docs/designs/5.outputs/gen_table.js similarity index 100% rename from docs/designs/outputs/gen_table.js rename to docs/designs/5.outputs/gen_table.js diff --git a/docs/designs/outputs/index.md b/docs/designs/5.outputs/index.md similarity index 100% rename from docs/designs/outputs/index.md rename to docs/designs/5.outputs/index.md diff --git a/docs/generate_summary.py b/docs/generate_summary.py new file mode 100755 index 0000000..8768ec4 --- /dev/null +++ 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]} ") + 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 b/docs/references/1.configurable.md similarity index 56% rename from docs/reference/configurable.md rename to docs/references/1.configurable.md index 7047976..15d6673 100644 --- a/docs/reference/configurable.md +++ b/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 b/docs/references/2.benchmarks_scope.md similarity index 100% rename from docs/reference/benchmarks_scope.md rename to docs/references/2.benchmarks_scope.md diff --git a/docs/reference/builders_scope.md b/docs/references/3.builders_scope.md similarity index 100% rename from docs/reference/builders_scope.md rename to docs/references/3.builders_scope.md diff --git a/docs/usages/building_outputs.md b/docs/usages/1.building_outputs.md similarity index 100% rename from docs/usages/building_outputs.md rename to docs/usages/1.building_outputs.md diff --git a/docs/usages/configuring.md b/docs/usages/2.configuring.md similarity index 100% rename from docs/usages/configuring.md rename to docs/usages/2.configuring.md diff --git a/docs/usages/examples.md b/docs/usages/3.examples.md similarity index 100% rename from docs/usages/examples.md rename to docs/usages/3.examples.md diff --git a/docs/usages/running/emulators.md b/docs/usages/4.running/emulators.md similarity index 100% rename from docs/usages/running/emulators.md rename to docs/usages/4.running/emulators.md diff --git a/docs/usages/running/gem5.md b/docs/usages/4.running/gem5.md similarity index 99% rename from docs/usages/running/gem5.md rename to docs/usages/4.running/gem5.md index f1d5833..c84c620 100644 --- a/docs/usages/running/gem5.md +++ b/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 b/docs/usages/4.running/index.md similarity index 100% rename from docs/usages/running/index.md rename to docs/usages/4.running/index.md diff --git a/docs/usages/running/nemu.md b/docs/usages/4.running/nemu.md similarity index 100% rename from docs/usages/running/nemu.md rename to docs/usages/4.running/nemu.md