Using Tablegen to Generate Op Documentation (#74)

* Add dialect documentation.

* Add a step in our CI to ensure documentation is up-to-date.

* Add dialect documentation.

* Fix config file mistake, using multi-line commands.

* Fix a bug in DocCheck.

.circleci/config.yml

@@ -44,6 +44,13 @@ jobs:
       - run:
           name: Run DocCheck
           command: cd ONNF/build && cmake --build . --target check-doc
+      - run:
+          name: Ensure tablegen documentation is up-to-date
+          command: |
+            cd ONNF/build
+            cmake --build . --target onnf-doc
+            # Check whether dialect documentation is up-to-date.
+            diff doc/Dialects ../doc/Dialects
       - run:
           name: Print the Current Time
           command: date

MLIR.cmake

@@ -207,3 +207,23 @@ add_executable(mlir-tblgen IMPORTED)
 set_property(TARGET mlir-tblgen
         PROPERTY IMPORTED_LOCATION ${LLVM_PROJ_BUILD}/bin/mlir-tblgen)
 set(MLIR_TABLEGEN_EXE mlir-tblgen)
+
+# Add a dialect used by ONNF and copy the generated operation
+# documentation to the desired places.
+# c.f. https://github.com/llvm/llvm-project/blob/e298e216501abf38b44e690d2b28fc788ffc96cf/mlir/CMakeLists.txt#L11
+function(add_onnf_dialect_doc dialect dialect_tablegen_file)
+  # Generate Dialect Documentation
+  set(LLVM_TARGET_DEFINITIONS ${dialect_tablegen_file})
+  onnf_tablegen(${dialect}.md -gen-op-doc)
+  set(GEN_DOC_FILE ${ONNF_BIN_ROOT}/doc/Dialects/${dialect}.md)
+  add_custom_command(
+          OUTPUT ${GEN_DOC_FILE}
+          COMMAND ${CMAKE_COMMAND} -E copy
+          ${CMAKE_CURRENT_BINARY_DIR}/${dialect}.md
+          ${GEN_DOC_FILE}
+          DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${dialect}.md)
+  add_custom_target(${dialect}DocGen DEPENDS ${GEN_DOC_FILE})
+  add_dependencies(onnf-doc ${dialect}DocGen)
+endfunction()
+
+add_custom_target(onnf-doc)

doc/doc_check/directive.py

@@ -44,7 +44,15 @@ class Directive(object):
         :param directive_config: a list used to output parsed directive configuration.
         :return: parse result.
         """
-        line = ctx.doc_file.next_non_empty_line()
+        try:
+            line = ctx.doc_file.next_non_empty_line()
+        except RuntimeError as e:
+            # Do not raise exception when next non-empty line
+            # does not exist. Instead, return failure.
+            if str(e) != "Enf of file.":
+                raise
+            return failure()
+
         matches = self.ext_to_patterns[ctx.doc_file_ext()].findall(line)
         if len(matches) > 1:
             raise ValueError("more than one directives in a line")

src/CMakeLists.txt

@@ -39,8 +39,10 @@ add_dependencies(compiler gen_onnx_combine)
 set(LLVM_TARGET_DEFINITIONS dialect/onnx/onnx.td)
 onnf_tablegen(onnx.hpp.inc -gen-op-decls "-I${CMAKE_SOURCE_DIR}/compiler/pass")
 onnf_tablegen(onnx.cpp.inc -gen-op-defs "-I${CMAKE_SOURCE_DIR}/compiler/pass")
+set(GEN_DOC_FILE ${CMAKE_BINARY_DIR}/docs/Dialects/onnx.md)
 add_public_tablegen_target(gen_onnx)
 add_dependencies(compiler gen_onnx)
+add_onnf_dialect_doc(onnx dialect/onnx/onnx.td)
 
 set(LLVM_TARGET_DEFINITIONS dialect/krnl/krnl_ops.td)
 onnf_tablegen(krnl.hpp.inc -gen-op-decls)