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. https://github.com/llvm/llvm-project/pull/190354 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
