feat: add summary for easier usage (#426)

.readthedocs.yaml

@@ -3,6 +3,9 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.13"
+  jobs:
+    pre_build:
+      - cd next && python3 llm.py && cd ..
 
 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.
 
+[Download this section in Markdown](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.
 
+[Download this section in Markdown](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/locales/zh_CN/LC_MESSAGES/example.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: MoonBit Document \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-01-03 11:03+0800\n"
+"POT-Creation-Date: 2025-01-16 15:44+0800\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language: zh_CN\n"
@@ -2711,7 +2711,7 @@ msgid ""
 "Nevertheless, it is undoubtedly an intriguing technology!"
 msgstr ""
 
-#: ../../example/gmachine/index.md:7 ../../example/index.md:5
+#: ../../example/gmachine/index.md:7 ../../example/index.md:7
 #: ../../example/myers-diff/index.md:3 ../../example/segment-tree/index.md:13
 msgid "Contents:"
 msgstr "目录："
@@ -2743,6 +2743,10 @@ msgstr "例子"
 msgid "Here are some examples built with MoonBit."
 msgstr "这里有一些用 MoonBit 构建的例子"
 
+#: ../../example/index.md:5
+msgid "[Download this section in Markdown](path:/download/example/summary.md)"
+msgstr "[下载本章节的 Markdown 版本](path:/download/example/summary.md)"
+
 #: ../../example/lambda/index.md:1
 msgid "Lambda calculus"
 msgstr "Lambda 演算"

next/locales/zh_CN/LC_MESSAGES/language.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: MoonBit Document \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-01-10 17:54+0800\n"
+"POT-Creation-Date: 2025-01-16 15:44+0800\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language: zh_CN\n"
@@ -5693,6 +5693,10 @@ msgstr "先进的编译时性能。"
 msgid "Simple but practical, data-oriented language design."
 msgstr "简单且实用的数据导向语言设计。"
 
+#: ../../language/index.md:18
+msgid "[Download this section in Markdown](path:/download/language/summary.md)"
+msgstr "[下载本章节的 Markdown 版本](path:/download/language/summary.md)"
+
 #: ../../language/introduction.md:1
 msgid "Introduction"
 msgstr "概述"

next/locales/zh_CN/LC_MESSAGES/toolchain.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: MoonBit Document \n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-12-31 16:38+0800\n"
+"POT-Creation-Date: 2025-01-16 15:44+0800\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language: zh_CN\n"
@@ -19,7 +19,7 @@ msgstr ""
 "Content-Transfer-Encoding: 8bit\n"
 "Generated-By: Babel 2.16.0\n"
 
-#: ../../toolchain/index.md:9 ../../toolchain/moon/index.md:3
+#: ../../toolchain/index.md:11 ../../toolchain/moon/index.md:3
 msgid "Contents:"
 msgstr "内容："
 
@@ -47,6 +47,10 @@ msgstr "VSCode扩展"
 msgid "..."
 msgstr ""
 
+#: ../../toolchain/index.md:9
+msgid "[Download this section in Markdown](path:/download/toolchain/summary.md)"
+msgstr "[下载本章节的 Markdown 版本](path:/download/toolchain/summary.md)"
+
 #: ../../toolchain/moon/commands.md:1
 msgid "Command-Line Help for `moon`"
 msgstr "`moon`的命令行帮助"