AaronBallman wrote: > > 1. 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. > > This comment surprised me. My understanding is that LLVM documentation is > moving towards markdown. Why don't we want to do this with Clang?
We had an RFC for that but it never gained consensus: https://discourse.llvm.org/t/rfc-markdown-for-documentation/48154 and I'm unaware of anything since then that's changed the status quo. Especially because .md doesn't support all of the use cases we need in Sphinx (e.g., it doesn't produce man pages which is something we do for command line tool documentation). There are tools out there like pandoc which could be used to alleviate some of those concerns, but that involves maintenance for build bots that nobody has agreed to. I know some folks have changed files to be markdown (like maintainers files) because GitHub wasn't rendering .rst files at one point, but that's no longer the case today (e.g., https://github.com/llvm/llvm-project/blob/main/clang/docs/ClangTools.rst) and this file format inconsistency has caused [confusion](https://discourse.llvm.org/t/which-doc-format-to-use-inline-doxygen-rst-markdown/89867) for us in practice, so I consider the existing .md files to be tech debt currently. https://github.com/llvm/llvm-project/pull/190354 _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
