1. Add the building util of Python

for the markdown docs.
2. Update the deploy.sh

docs/utils/.gitignore

@@ -0,0 +1 @@
+__pycache__

docs/utils/build_markdown.py

@@ -0,0 +1,87 @@
+"""
+File: build_markdown_docs.py
+Created Time: 2023-02-06
+Author: Krahets (krahets@163.com)
+"""
+
+import sys, os.path as osp
+sys.path.append(osp.dirname(osp.dirname(osp.dirname(osp.abspath(__file__)))))
+
+import re
+import glob
+import shutil
+from docs.utils.extract_code_python import ExtractCodeBlocksPython
+
+def build_markdown(md_path):
+    with open(md_path, "r") as f:
+        lines = f.readlines()
+    
+    code_blocks_dict = {}
+    file_pattern = re.compile(r'\s*```(\w+)\s+title="(.+)"')
+    src_pattern = re.compile(r'\s*\[class\]\{(.*?)\}-\[func\]\{(.*?)\}')
+    for i in range(len(lines)):
+        # Find the line target to the source codes
+        src_match = src_pattern.match(lines[i])
+        if src_match is None:
+            continue
+        for j in range(i - 1, -1 ,-1):
+            file_match = file_pattern.match(lines[j])
+            if file_match is not None:
+                break
+        
+        # Get code blocks
+        lang = file_match[1]
+        file_name = file_match[2]
+        if file_name not in code_blocks_dict:
+            code_blocks_dict[file_name] = ExtractCodeBlocksPython(
+                file_path=osp.dirname(md_path).replace("docs/", f"codes/{lang}/") + f"/{file_name}")
+
+        header_line = i
+        class_label =  src_match[1]
+        func_label = src_match[2]
+        code_blocks = code_blocks_dict[file_name]
+        src_info = {
+            "line_number": i,
+            "class_label": src_match[1],
+            "func_label": src_match[2],
+            "code_blocks": code_blocks_dict[file_name]
+        }
+
+        # Add the class to the doc
+        if not func_label and class_label:
+            if class_label in code_blocks.classes:
+                lines.pop(header_line)
+                class_block = code_blocks.classes[class_label]["block"]
+                for code_line in class_block[::-1]:
+                    ind = " " * 4 if code_line != "\n" else ""
+                    lines.insert(header_line, ind + code_line)
+        # Add the function to the doc
+        elif func_label and not class_label:
+            if func_label in code_blocks.functions:
+                lines.pop(header_line)
+                func_block = code_blocks.functions[func_label]
+                for code_line in func_block["block"][::-1]:
+                    ind = " " * 4 if code_line != "\n" else ""
+                    lines.insert(header_line, ind + code_line)
+        # Add the class method to the doc
+        elif func_label and class_label:
+            if class_label in code_blocks.classes:
+                class_dict = code_blocks.classes[class_label]
+                if func_label in class_dict["functions"]:
+                    lines.pop(header_line)
+                    func_block = class_dict["functions"][func_label]
+                    for code_line in func_block["block"][::-1]:
+                        lines.insert(header_line, code_line)
+                    
+    with open(md_path.replace("docs/", "build/"), "w") as f:
+        f.writelines(lines)
+        print(f"Built {md_path}")
+
+
+if __name__ == "__main__":
+    # Copy files to the build dir
+    shutil.copytree("docs", "build", dirs_exist_ok=True)
+    shutil.rmtree("build/utils")
+    # Build docs
+    for md_path in glob.glob("docs/chapter_*/*.md"):    
+        build_markdown(md_path)

docs/utils/deploy.sh

@@ -0,0 +1,8 @@
+# This script is borrowed from https://gist.github.com/cobyism/4730490
+
+git add build && git commit -m "build"
+git subtree push --prefix build origin built-docs
+
+mkdocs build --clean
+git add site && git commit -m "deploy"
+git subtree push --prefix site origin gh-pages

docs/utils/extract_code_python.py

@@ -0,0 +1,117 @@
+"""
+File: extract_code_python.py
+Created Time: 2023-02-06
+Author: Krahets (krahets@163.com)
+"""
+
+import re
+import os
+import os.path as osp
+import glob
+
+class ExtractCodeBlocksPython:
+    def __init__(self, file_path) -> None:
+        self.file_path = file_path
+        with open(file_path) as f:
+            self.lines = f.readlines()
+            self.content = "".join(self.lines)
+            
+        # Regular expression pattern to match function names and class names
+        self.func_pattern = re.compile(r'(\s*)def\s+(\w+)\s*\(')
+        self.class_pattern = re.compile(r'class\s+(\w+)')
+        
+        # Detect and extract all the classes and fucntions
+        self.classes = self.extract_class_blocks()
+        self.functions = self.extract_function_blocks()
+
+    def search_block(self, header_line, indentation):
+        """
+        Search class/function block given the header_line and indentation
+        """
+        start_line, end_line = 0, len(self.lines)
+        # Search the code
+        for i in range(header_line + 1, len(self.lines)):
+            if re.search("^\s*\n|^\s{ind}\s+.+\n".replace("ind", str(indentation)),
+                         self.lines[i]) is None:
+                end_line = i
+                break
+        # Search the header comment
+        for i in range(header_line - 1, -1, -1):
+            if re.search('^\s{ind}""".+'.replace("ind", str(indentation)), 
+                         self.lines[i]) is not None:
+                start_line = i
+                break
+        func_block = self.lines[start_line:end_line] 
+        # Remove empty lines at bottom
+        for i in range(len(func_block) - 1, -1, -1):
+            if re.search("^\s*\n", func_block[i]) is None:
+                break
+            end_line -= 1
+        
+        return start_line, end_line, self.lines[start_line:end_line]
+        
+
+    def extract_function_blocks(self, indentation=0, start_line=-1, end_line=-1):
+        """
+        Extract all the functions with given indentation
+        """
+        functions = {}
+        
+        if start_line == -1:
+            start_line = 0
+        if end_line == -1:
+            end_line = len(self.lines) - 1
+            
+        for line_num in range(start_line, end_line + 1):
+            # Search the function header
+            func_match = self.func_pattern.match(self.lines[line_num])
+            if func_match is None: continue
+            # The function should match the input indentation
+            if len(func_match.group(1)) != indentation: continue
+            header_line = line_num
+            
+            # Search the block from the header line
+            start_line, end_line, func_block = self.search_block(header_line, indentation)
+            # Construct the functions dict
+            func_label = func_match.group(2)
+            functions[func_label] = {
+                "indentation": indentation,
+                "line_number": {
+                    "start": start_line,
+                    "end": end_line,
+                    "header": header_line,
+                },
+                "block": func_block,
+            }
+        
+        return functions
+
+    def extract_class_blocks(self):
+        """
+        Extract all the classes with given indentation
+        """
+        classes = {}
+        
+        for line_num, line in enumerate(self.lines):
+            # Search the class header
+            class_match = self.class_pattern.match(line)
+            if class_match is None: continue
+            header_line = line_num
+            
+            # Search the block from the header line
+            start_line, end_line, class_block = self.search_block(header_line, 0)
+            # Construct the classes dict
+            class_label = class_match.group(1)
+            classes[class_label] = {
+                "indentation": 0,
+                "line_number": {
+                    "start": start_line,
+                    "end": end_line,
+                    "header": header_line,
+                },
+                "block": class_block,
+                "functions": self.extract_function_blocks(
+                    indentation=4, start_line=start_line, end_line=end_line)
+            }
+        
+        return classes