[clang] [clang][CIR][doc] Add auto-generated ClangIR documentation (PR #190354)

[Sirui Mu via cfe-commits]

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