feat: add summary for easier usage

.readthedocs.yaml

@@ -3,6 +3,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.13"
+  jobs:
+    pre_build:
+      - python3 next/llm.py
 
 sphinx:
   configuration: next/conf.py

next/.gitignore

@@ -1,4 +1,5 @@
 _build
 *.mo
 __pycache__
-.env
+.env
+download

next/conf.py

@@ -31,7 +31,7 @@
 extensions = ['myst_parser', 'lexer', 'check', 'indent', 'sphinx_copybutton']
 
 templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', ".env", '.venv', "README.md", 'sources']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', ".env", '.venv', "README.md", 'sources', 'download']
 
 smartquotes_excludes = {
   'builders': ['man', 'text', 'markdown', 'latex'],

next/example/index.md

@@ -2,6 +2,8 @@
 
 Here are some examples built with MoonBit.
 
+[Summary of this section](path:/download/example/summary.md)
+
 ```{toctree}
 :maxdepth: 2
 :caption: Contents:

next/language/index.md

@@ -15,6 +15,8 @@ When MoonBit reaches beta, it means any backwards-incompatible changes will be s
 - State of the art compile-time performance.
 - Simple but practical, data-oriented language design.
 
+[Summary of this section](path:/download/language/summary.md)
+
 ```{toctree}
 :hidden:
 introduction

next/llm.py

@@ -1,17 +1,60 @@
+import os
+import sys
+
 BUILD_DIR="_build/markdown"
 
-filenames = ["index.md", "tutorial/tour.md", "language/index.md", "language/introduction.md",
-             "language/fundamentals.md", "language/methods.md", "language/error-handling.md",
-             "language/packages.md", "language/tests.md", "language/docs.md", "language/ffi-and-wasm-host.md",
-             "language/derive.md", "language/async-experimental.md"]
+def collect(directory, header_level, output_file):
+    def adjust_header(line, level):
+        if line.startswith('#'):
+            return '#' * level + line
+        return line
+
+    def process_file(filepath, level, output):
+        output.write(f"\n<!-- path: {filepath} -->\n")
+        with open(os.path.join(BUILD_DIR, filepath), "r") as file:
+            for line in file:
+                output.write(adjust_header(line, level))
+
+    index_path = os.path.join(directory, "index.md")
+    with open(index_path, "r") as index_file:
+        toctree_paths = []
+        collect_paths = False
+        for line in index_file:
+            line = line.strip()
+            if "toctree" in line:
+                collect_paths = True
+                continue
+            if collect_paths:
+                if line.startswith(":"):
+                    continue
+                if line == "```":
+                    break
+                toctree_paths.append(os.path.join(directory, f"{line}.md"))
 
-with open(f"{BUILD_DIR}/llm.md", "w") as f:
-  print("# MoonBit Documentation", file=f)
-  for fname in filenames:
-    with open(f"{BUILD_DIR}/{fname}", "r") as g:
-      print(f"<!-- path: {fname} -->", file=f)
+    with open(output_file, "a") as output:
+        process_file(index_path, header_level, output)
+        for path in toctree_paths:
+            process_file(path, header_level + 1, output)
+
+def llms_txt():
+  with open(f"{BUILD_DIR}/llm.md", "w") as f:
+    with open(f"{BUILD_DIR}/index.md", "r") as g:
+      print(f"<!-- path: index.md -->", file=f)
       for line in g:
-        if line.startswith('#'):
-          f.write(f"#{line}")
-        else:
-          f.write(line)
+        f.write(line)
+
+  collect("tutorial", 1, f"{BUILD_DIR}/llm.md")
+  collect("language", 1, f"{BUILD_DIR}/llm.md")
+
+def main():
+  os.system("make markdown")
+  llms_txt()
+  for directory in ["tutorial", "language", "toolchain", "example"]:
+    output_file = f"download/{directory}/summary.md"
+    os.makedirs(os.path.dirname(output_file), exist_ok=True)
+    if os.path.exists(output_file):
+      os.remove(output_file)
+    collect(directory, 0, output_file)
+
+if __name__ == "__main__":
+  main()

next/toolchain/index.md

@@ -6,6 +6,8 @@ Here are some manuals that may help you use the toolchains of the programming la
 - VSCode extension
 - ...
 
+[Summary of this section](path:/download/toolchain/summary.md)
+
 ```{toctree}
 :maxdepth: 2
 :caption: Contents:

next/tutorial/index.md

@@ -5,6 +5,8 @@ Here are some tutorials that may help you learn the programming language:
 - [An interactive tour with language basics](https://tour.moonbitlang.com)
 - [Tour for Beginners](./tour.md)
 
+[Summary of this section](path:/download/tutorial/summary.md)
+
 ```{toctree}
 :hidden:
 tour