I’m a bit confused that we have 3 ways of documenting this.
In particular, I want to document a somewhat complicated API - that to be used correctly - one needs to apply changes at multiple places. This means that the example is like 80 lines.
In the past, I would have just made an rst file in the docs directory, but those tend to get out of sync from the code. Given that the example would use multiple functions, etc. I want to keep it in-sync with those.
Consequently, what I think is: the closer they are to those APIs the better the chances of keeping those in-sync. So it’s Doxygen.
Now that the Maintainers.rst was ported to Markdown last week, I wonder if in general there is a shift away from rst?
I find rst annoying to work with every time I have to touch it, because I constantly have to consult the reference on its syntax and various features, even for something as simple as a link. I enjoy working with markdown up until its features are sufficient for my needs. From this perspective, rst seems like much more powerful.
RST is still the requirement for long-form documentation that lives in a docs directory AFAIK. There have been some recent pushes to use .md for things like the maintainers file, but there’s been no RFC accepted which switches from RST to MD or any other markdown format, so these are ad hoc changes that may not be fully justified given the confusion they’re causing.
Of course we still have some documentation which is hand-written html living in www directories and doxygen comments which live in source files directly, which are appropriate to use depending on the situation, so this confusion is not really something new either.
I switched the llvm release notes to Markdown - RFC: Convert LLVM's Release Notes to Markdown. My justifications were specific to that file and the kind and frequency of contributions it gets. So as you say, not a global policy change.
For maintainer files, we had a mix of formats so anything converted from plain text, or a new file, I used Markdown. Mostly because of my own bias. The features of RST used for the average maintainer file all render well on Github itself, where people often read those files.
Long-term, I don’t think having two doc formats is a desirable state of the repository. New documentation should be written in .md and the .rst eventially updated to Markdown (like I did here). If RestructuredText remains the standard, would should not have introduced Markdown in the first place. See the initial discussion, [RFC] Markdown for documentation
doxygen is complementary to the Sphinx-generated documentation.
Only agreed if there’s a commitment from someone to actually do that transition, otherwise, we end up having two doc formats forever. This is not a transition that will happen organically as people add docs (reviewers aren’t going to obligate someone adding incremental docs to something like llvm-project/clang/docs/LanguageExtensions.rst at main · llvm/llvm-project · GitHub to first convert it to .md)
I do think Markdown is preferable for most docs, but I believe we should keep the usage of RST for command line tool docs. Otherwise it will no longer be possible to produce man pages with plain sphinx.
That suggests to me we should convert the .md files to .rst because .md isn’t able to meet our requirements. However, maybe pandoc can be used to generate man pages from .md files? I’m not familiar enough with it to know, but if it is, maybe we could convert .rst to .md files and then make pandoc a requirement for folks who need to build man pages? (Maybe that’s a big ask, I don’t know, I’m just trying to find a solution where we eventually have ONE markdown format.)
