AaronBallman wrote: > > > > > Clang's documentation should consistently be in .rst files; there > > > > > have been a few things moved to `.md` but those changes have been > > > > > questioned enough that we should not use it as precedent for adding > > > > > more .md files. > > > > > > > > > > > > > I don't think we should disable this diagnostic; MLIR should not > > > > > generate invalid markdown code blocks in the first place IMO. > > > > > > > > > > > > The main problem here is that we have a conflict with what > > > > `mlir-tblgen` follows: > > > > > > > > 1. `mlir-tblgen` does not generate `.rst` files. It emits `.md` files > > > > only. > > > > 2. `mlir-tblgen` generates Markdown code blocks of language `mlir`, > > > > which is not recognized by Sphinx. > > > > > > > > With some more post-processing on the output material of `mlir-tblgen`, > > > > we could replace all `mlir` code blocks with a plaintext code block, > > > > thus resolving problem 2. > > > > I don't see an easy way to bypass problem 1 if we intend to follow a > > > > strict `.rst` policy now. Teaching `mlir-tblgen` to generate `.rst` > > > > files could work, but it requires non-trivial amount of additional work > > > > on implementation and maintenance. > > > > > > > > > Thank you for the background information! This is another case where it's > > > a bit awkward that MLIR picked a different approach from the rest of the > > > project (we've run into this previously with CIR around naming convention > > > choices too). I'd prefer mlir-tblgen didn't have to know how to spit out > > > .rst and .md files because that seems rather silly, but it's also not > > > reasonable to expect the Clang community worsen our tech debt in this > > > area either. On balance, I think I'd rather the tool be updated to handle > > > either format on the assumption that 1) MLIR doesn't want to change away > > > from .md and Clang should not force them to, 2) Clang doesn't want more > > > inconsistency with .md and .rst and MLIR should not force us to, 3) .rst > > > and .md markdown formats are sufficiently similar this isn't a huge > > > implementation or maintenance burden to support both. #3 is pure > > > speculation on my part though, so maybe I'm off-base? > > > > > > Is it acceptable for clang if `.md` files only appear in the build tree of > > the documents? We could let the tool generate `.md` files directly into the > > documentation's build tree and include those `.md` files into the document. > > No `.md` files in the source tree. This would be an easier short-term > > solution if it's acceptable. > > I think it's reasonable to consider but my primary concern remains that when > things go sideways because of .md vs .rst differences, it's going to be > painful for us to debug, making it a maintenance concern. Short-term > solutions have a habit of becoming long-term solutions and CIR is new > technology, so my preference is still for the tool to produce .rst directly > unless that's a bigger burden than I realize I'm asking for.
I'll walk this back a little bit -- the concern is around what happens when the tool produces .md that's incompatible with what Sphinx can handle and so we either get rendering issues with the output or build failures. So if the tool only produces .md which Sphinx is capable of handling, then there's really not an issue for the tool to produce .md as intermediary output the community never has to see. But this would mean any rendering or build issue is classified as a bug with mlir-tblgen rather than something we'd try to address within Clang. https://github.com/llvm/llvm-project/pull/190354 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
