Hosting Fortran IR (FIR) documentation

The current Flang website ( is based on Sphinx. I believe Sphinx generates the website based on contents in the docs directory of the flang repo. We were thinking about what would be the best way to host the documentation generated while processing the FIR Op definition file. I see that the MLIR website ( is generated and hosted using Hugo from contents in And there is a GitHub actions CI that generates the documentation nightly to keep things updated. The CIRCT project also seems to be using a similar mechanism. Would this be the right path to choose if we want to host the FIR documentation as well? Or is there a way to generate and populate the FIR documentation through the current Sphinx mechanism?

The docs generated for dialects are just markdown (well we use tags like TOC which aren’t standard markdown that we handle vis plugin and could also be handled with some postprocessing script) and it seems Sphinx supports markdown. Now if course markdown isn’t as standardized as I thought it is, but we aren’t doing anything fancy there. So one could keep Sphinx and supplement it with something that builds the docs/runs Tblgen. I don’t know Sphinx at all to know if there is a plugin mechanism that this could hook in to vs just a plain old script/GitHub action which invokes Sphinx doc gen at the end. Unless I misunderstood the question.

1 Like

Thanks @jpienaar.

The current Sphinx flow is possibly just going over the contents of the flang/docs folder and generating the HTML pages. But I assume for MLIR-related documentation there is MLIR code (or at least some tablegen) that has to be built to do some processing before documentation generation. I was thinking that it might not be a good idea to add that processing to the existing Sphinx flow.

I was also wondering why MLIR chose to go with a different flow rather than choosing to use the Sphinx flow.

Maybe you can add a:
ninja install-fir-ops-md

@mehdi_amini is only one that can answer that one :slight_smile: I think it was merely a practical consideration while we were in process of OSS’ng, not something we did too deep investigation and just went for something that worked and we needed to set up builders etc and weren’t inside LLVM repo.

I never quite understood what Sphinx would bring us actually?
The LLVM website (as in the homepage ) isn’t built with Sphinx, only the doc here About — LLVM 16.0.0git documentation is. It always seemed weird to me that this isn’t more unified, so what we did with MLIR is write our doc in markdown (Sphinx supports markdown as well) and use one infrastructure for HTML generation so that the entire website is written in markdown and integrated in one framework.

1 Like

Finally, we decided to stick with Sphinx-generated HTML pages for now since that was enough for our purpose.

Nice. Do you have Sphinx parse the markdown generated? Any issues you ran in to with that?

We ran into a small problem where the Design Documents list on Flang’s docs would generate a link for every entry in FIRLangRef, rather than just one link to the page. On top of that, the first entry in the LangRef would incorrectly format, and so the title of the page would become 'fir.absent.

We found that adding a header to the top of the markdown file to create an introduction fixed both of these problems, so it was likely that sphinx expecting some title/introduction for each page that wasn’t present by default in