[PATCH] D85828: [Flang] Move mark down documentation(md) files to reStructuredText(rst) file format.

[sameeran joshi via Phabricator via llvm-commits]

sameeranjoshi added a comment.

Thanks for detailed information @mehdi_amini and all folks.
**TL;DR version:**
There is a sweet spot on this issue.
Sphinx supports now `.md` files.
LLVM has as well added changes in config files to pick up `.md` files, needs to extend this to flang.

**Long version:**

Sphinx has a support for markdown format files, but it supports commonmark based markdown flavour[1].
As there are tons of implementations of markdown format, commonmark is a project which standardizes the way we write markdown files.
Github has commonmark flavour supported with some extra specifications/features which they call GFM(Github Flavored Markdown[2])
Github's way of writing markdown files is a subset <https://www.google.com/search?rlz=1C1GCEU_enIN908IN908&ei=yUI0X8-UM7KQmge-r6jQDw&q=gfm+vs+commonmark&oq=gfm+commonmark+&gs_lcp=CgZwc3ktYWIQAxgBMgYIABAWEB4yBggAEBYQHjoHCAAQRxCwAzoECAAQQzoFCAAQkQI6CAgAELEDEIMBOggILhCxAxCDAToKCAAQsQMQgwEQQzoHCAAQsQMQQzoFCAAQsQM6AggAOgQIABAKOgUILhCxAzoICC4QxwEQrwE6AgguOggIABAWEAoQHjoCCCY6BggAEA0QHlDiH1j6VmCaamgAcAB4AIABqgOIAcwbkgEJMC43LjcuMS4xmAEAoAEBqgEHZ3dzLXdpesABAQ&sclient=psy-ab> of commonmark.

So I think that should not be an issue for rendering the current `.md` files unless people have unknowingly referred GFM and written some parts of the documentation, in that case some changes in documentation would be needed.

Unfortunately, there was a commit[3] in llvm-core long time back which supported this commonmark based format(to move towards `.md` files) into llvm sphinx builds and buildbots and I guess no sub-project ever used it except to some extent LLVM.

I have fragmented this patch into 2 patches:

1. To move files to `docs/` folder - https://reviews.llvm.org/D85884
2. I plan to add support for `.md` files in sphinx using the way LLVM recommends[4] in a later patch.

[1] https://www.sphinx-doc.org/en/master/usage/markdown.html
[2] https://guides.github.com/features/mastering-markdown/
[3] https://reviews.llvm.org/D44910
[4] https://github.com/llvm/llvm-project/commits/master/llvm/docs/MarkdownQuickstartTemplate.md


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D85828/new/

https://reviews.llvm.org/D85828