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