Lancern wrote:
I've updated this PR according to the feedback. Here are a brief summary of the
changes:
- It turns out that `mlir-tblgen` could indeed generate a complete document
page (in `.md` format) with `-gen-dialect-doc`. Thus, I removed that Markdown
template file from the CIR document tree. Now we don't have extra `.md` files
in the CIR document tree besides those two previously moved from `clang/docs`.
I think it's fine to migrate these two Markdown documents to `.rst` format in a
follow-up PR.
- I removed the suppression of the `misc.highlighting_failure` warning as
required by Aaron. It turns out that all these problematic `mlir` Markdown code
blocks come from CIR's TableGen definitions, so I updated our TableGen
definition and replaced all `mlir` Markdown code blocks with plain-text code
blocks.
<hr>
The post-processing script for auto-generated CIR documents is kept due to two
reasons:
- `mlir-tblgen` output still contains Sphinx-incompatible contents that need to
be fixed. Specifically, `mlir-tblgen` writes a placeholder `[TOC]` for
table-of-contents, and we need to follow Sphinx's rule to replace it with
something like:
```
```{contents}
---
local:
depth: 2
---
```
- Currently CIR is built behind a CMake flag, thus the post-processing script
needs to tweak the clang document's toctree based on whether CIR documents are
available.
<hr>
I made some attempts to teach `mlir-tblgen` to directly generate documents in
`.rst` formats, but it turns out this is more difficult than I thought. The
problem is that MLIR allows you to write documentation in TableGen:
https://github.com/llvm/llvm-project/blob/9ab2c5732642a85de8e218e81663d5e458744de0/clang/include/clang/CIR/Dialect/IR/CIROps.td#L279-L329
The `description` field as shown above holds a detailed documentation for the
`cir.dyn_cast` op. Unfortunately, [MLIR's official
document](https://mlir.llvm.org/docs/DefiningDialects/Operations/#operation-documentation)
says this description should be written in Markdown format:
> description should be written in Markdown syntax.
So it seems like that it won't be an easy task to simply add `.rst` output
support to `mlir-tblgen` without a more involved discussion and development
with the MLIR team.
https://github.com/llvm/llvm-project/pull/190354
_______________________________________________
cfe-commits mailing list
[email protected]
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
