From ea66b7654bf6b2b67e74bc247c6b94f9d175f03b Mon Sep 17 00:00:00 2001 From: xumingkuan Date: Sat, 27 Feb 2021 17:51:39 +0800 Subject: [PATCH 1/5] [ir] Generate yaml documentation for statement classes --- misc/generate_ir_design_doc.py | 47 ++++++++++++++++++++++++++++++++++ taichi/ir/statements.h | 10 +++++++- 2 files changed, 56 insertions(+), 1 deletion(-) create mode 100644 misc/generate_ir_design_doc.py diff --git a/misc/generate_ir_design_doc.py b/misc/generate_ir_design_doc.py new file mode 100644 index 0000000000000..4a49f0a018062 --- /dev/null +++ b/misc/generate_ir_design_doc.py @@ -0,0 +1,47 @@ +import taichi as ti +import os +import yaml + +repo_dir = ti.get_repo_directory() +statements_fn = os.path.join(repo_dir, 'taichi/ir/statements.h') +with open(statements_fn, 'r') as f: + statements = f.readlines() + +class_doc = {} + +for i in range(len(statements)): + line = statements[i] + start_pos = line.find('/**') + if start_pos == -1: + continue + current_doc = line[start_pos + 3:].strip() + doc_ends_at_line = 0 + for j in range(i + 1, len(statements)): + next_line = statements[j] + end_pos = next_line.find('*/') + if end_pos != -1: + doc_ends_at_line = j + break + next_line = next_line.strip() + if next_line.startswith('*'): + next_line = next_line[1:].strip() + if next_line == '': # an empty line + current_doc += '\n' + else: + current_doc += ' ' + next_line + current_doc = current_doc.strip() + + line = statements[doc_ends_at_line + 1] + start_pos = line.find('class') + if start_pos == -1: + print('We only support doc for classes now. ' + f'The following doc at line {i}-{doc_ends_at_line} ' + 'cannot be recognized:\n' + f'{current_doc}') + continue + class_name = line[start_pos + 5:].strip().split()[0] + class_doc[class_name] = current_doc + +doc_filename = 'ir_design_doc.yml' +with open(doc_filename, 'w') as f: + yaml.dump(class_doc, f, Dumper=yaml.SafeDumper) diff --git a/taichi/ir/statements.h b/taichi/ir/statements.h index d5ac7b27ddc1e..c65890dc5cec0 100644 --- a/taichi/ir/statements.h +++ b/taichi/ir/statements.h @@ -6,6 +6,9 @@ TLANG_NAMESPACE_BEGIN +/** + * Allocate a local variable with initial value 0. + */ class AllocaStmt : public Stmt { public: AllocaStmt(DataType type) { @@ -30,7 +33,9 @@ class AllocaStmt : public Stmt { TI_DEFINE_ACCEPT_AND_CLONE }; -// updates mask, break if no active +/** + * Updates mask, break if no bits of the mask are active. + */ class WhileControlStmt : public Stmt { public: Stmt *mask; @@ -43,6 +48,9 @@ class WhileControlStmt : public Stmt { TI_DEFINE_ACCEPT_AND_CLONE; }; +/** + * Continue the current (innermost) loop. + */ class ContinueStmt : public Stmt { public: // This is the loop on which this continue stmt has effects. It can be either From 4ab1e52b1521e5892bffcceaef82b90e358dfab7 Mon Sep 17 00:00:00 2001 From: xumingkuan Date: Sat, 27 Feb 2021 18:13:54 +0800 Subject: [PATCH 2/5] Also generates markdown file --- misc/generate_ir_design_doc.py | 109 ++++++++++++++++++++------------- 1 file changed, 66 insertions(+), 43 deletions(-) diff --git a/misc/generate_ir_design_doc.py b/misc/generate_ir_design_doc.py index 4a49f0a018062..e1c66910a7912 100644 --- a/misc/generate_ir_design_doc.py +++ b/misc/generate_ir_design_doc.py @@ -2,46 +2,69 @@ import os import yaml -repo_dir = ti.get_repo_directory() -statements_fn = os.path.join(repo_dir, 'taichi/ir/statements.h') -with open(statements_fn, 'r') as f: - statements = f.readlines() - -class_doc = {} - -for i in range(len(statements)): - line = statements[i] - start_pos = line.find('/**') - if start_pos == -1: - continue - current_doc = line[start_pos + 3:].strip() - doc_ends_at_line = 0 - for j in range(i + 1, len(statements)): - next_line = statements[j] - end_pos = next_line.find('*/') - if end_pos != -1: - doc_ends_at_line = j - break - next_line = next_line.strip() - if next_line.startswith('*'): - next_line = next_line[1:].strip() - if next_line == '': # an empty line - current_doc += '\n' - else: - current_doc += ' ' + next_line - current_doc = current_doc.strip() - - line = statements[doc_ends_at_line + 1] - start_pos = line.find('class') - if start_pos == -1: - print('We only support doc for classes now. ' - f'The following doc at line {i}-{doc_ends_at_line} ' - 'cannot be recognized:\n' - f'{current_doc}') - continue - class_name = line[start_pos + 5:].strip().split()[0] - class_doc[class_name] = current_doc - -doc_filename = 'ir_design_doc.yml' -with open(doc_filename, 'w') as f: - yaml.dump(class_doc, f, Dumper=yaml.SafeDumper) + +def extract_doc(doc_filename=None): + repo_dir = ti.get_repo_directory() + statements_fn = os.path.join(repo_dir, 'taichi/ir/statements.h') + with open(statements_fn, 'r') as f: + statements = f.readlines() + + class_doc = {} + + for i in range(len(statements)): + line = statements[i] + start_pos = line.find('/**') + if start_pos == -1: + continue + current_doc = line[start_pos + 3:].strip() + doc_ends_at_line = 0 + for j in range(i + 1, len(statements)): + next_line = statements[j] + end_pos = next_line.find('*/') + if end_pos != -1: + doc_ends_at_line = j + break + next_line = next_line.strip() + if next_line.startswith('*'): + next_line = next_line[1:].strip() + if next_line == '': # an empty line + current_doc += '\n' + else: + current_doc += ' ' + next_line + current_doc = current_doc.strip() + + line = statements[doc_ends_at_line + 1] + start_pos = line.find('class') + if start_pos == -1: + print('We only support doc for classes now. ' + f'The following doc at line {i}-{doc_ends_at_line} ' + 'cannot be recognized:\n' + f'{current_doc}') + continue + class_name = line[start_pos + 5:].strip().split()[0] + class_doc[class_name] = current_doc + + if doc_filename is None: + doc_filename = 'ir_design_doc.yml' + with open(doc_filename, 'w') as f: + yaml.dump(class_doc, f, Dumper=yaml.SafeDumper) + + +def yml_to_md(yml_filename=None, md_filename=None): + if yml_filename is None: + yml_filename = 'ir_design_doc.yml' + if md_filename is None: + md_filename = 'ir_design_doc.md' + with open(yml_filename, 'r') as f: + doc_yml = yaml.load(f, Loader=yaml.SafeLoader) + doc_md = '' + for (class_name, class_doc) in doc_yml.items(): + doc_md += f'### {class_name}\n' + doc_md += class_doc + doc_md += '\n\n' + with open(md_filename, 'w') as f: + f.write(doc_md) + + +extract_doc() +yml_to_md() From 6978449706b2a82b9c8e8cc69caa13a34a39ddc7 Mon Sep 17 00:00:00 2001 From: xumingkuan Date: Sat, 27 Feb 2021 18:14:35 +0800 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Yuanming Hu --- taichi/ir/statements.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/taichi/ir/statements.h b/taichi/ir/statements.h index c65890dc5cec0..0bab658874c71 100644 --- a/taichi/ir/statements.h +++ b/taichi/ir/statements.h @@ -34,7 +34,7 @@ class AllocaStmt : public Stmt { }; /** - * Updates mask, break if no bits of the mask are active. + * Updates mask, break if all bits of the mask are 0. */ class WhileControlStmt : public Stmt { public: @@ -49,7 +49,7 @@ class WhileControlStmt : public Stmt { }; /** - * Continue the current (innermost) loop. + * Jump to the next loop iteration. I.e., "continue" in C++. */ class ContinueStmt : public Stmt { public: From 8a20a6495f965826ea175c63def3afedaf8660b2 Mon Sep 17 00:00:00 2001 From: xumingkuan Date: Mon, 1 Mar 2021 17:01:57 +0800 Subject: [PATCH 4/5] Update taichi/ir/statements.h Co-authored-by: Ye Kuang --- taichi/ir/statements.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/taichi/ir/statements.h b/taichi/ir/statements.h index 0bab658874c71..48cf1139fc815 100644 --- a/taichi/ir/statements.h +++ b/taichi/ir/statements.h @@ -49,7 +49,7 @@ class WhileControlStmt : public Stmt { }; /** - * Jump to the next loop iteration. I.e., "continue" in C++. + * Jump to the next loop iteration, i.e., `continue` in C++. */ class ContinueStmt : public Stmt { public: From df6e6ed0e4ac1ca0e4e8154155284a41d0c263af Mon Sep 17 00:00:00 2001 From: xumingkuan Date: Mon, 1 Mar 2021 17:11:12 +0800 Subject: [PATCH 5/5] Apply review --- misc/generate_ir_design_doc.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/misc/generate_ir_design_doc.py b/misc/generate_ir_design_doc.py index e1c66910a7912..6a33b39a964ed 100644 --- a/misc/generate_ir_design_doc.py +++ b/misc/generate_ir_design_doc.py @@ -66,5 +66,7 @@ def yml_to_md(yml_filename=None, md_filename=None): f.write(doc_md) -extract_doc() -yml_to_md() +if __name__ == '__main__': + extract_doc() + yml_to_md() + print('Done!')