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

sameeran joshi via Phabricator via flang-commits flang-commits at lists.llvm.org
Wed Aug 12 11:47:27 PDT 2020


sameeranjoshi added a comment.

+1 @DavidTruby - For pointing the reason for MLIR to use `.md` files.
It's correct that LLVM uses Sphinx infrastructure to build docs for any sub-project except MLIR.

> " If we want to do that and render the .md files to html instead then we can, but if we want to be on the same website as the rest of LLVM (except MLIR) we need to use rst as the text format."

I remember we had a light on this issue long back(initial doxygen support) given that we want something like `llvm.org/flang` or more technically similar `flang.llvm.org` we would need to move to `.rst` from `.md`.
https://github.com/flang-compiler/f18/pull/1065#issuecomment-606721800
https://github.com/flang-compiler/f18/pull/1065#issuecomment-606532420

Here's one such reference recently
https://reviews.llvm.org/D85470#2207363

I tried hard to find any reference from the developers policy to use `.rst` as documentation formats, with no exact mentioning I found below page
http://llvm.org/docs/SphinxQuickstartTemplate.html
mentioning a few points as

1. Sphinx to be more powerful than markdown file formats.
2. Sending the .rst file to llvm-commits for review.

Neither I am against using `.md` files nor I have much details on `.rst` files, but I doubt Flang would render using their own website as MLIR, hence going with the option with LLVM(sphinx build and `.rst` files) seemed reasonable to be to come up with this patch.

This patch has basically 2 changes :

1. Move files to `docs/` folder from `documentation/`
2. Change them to `.rst`

And I assume the first set of changes people agree upon & are the discussion seems to be around second point.
Thanks for reviewing all :)


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D85828



More information about the flang-commits mailing list