[Flang] Fix formatting for FIRLangRef.html

Previously, FIRLangRef.md was incorrectly formatted.
This was due to how FIRLangRef.md had no page header,
and so the first entry would render incorrectly.

This patch introduces a header file, which is prepended to the FIRLangRef
 before it becomes a HTML file. The header is currently brief
but can be expanded upon at a later date if required.

This formatting fix also means the index page
can correctly generate a link to FIRLangRef.html and as such,
this patch also removes FIRLangRef from the sidebar and adds it to the main list of links.

Depends on D128650

Reviewed By: kiranchandramohan

Differential Revision: https://reviews.llvm.org/D129186

flang/docs/CMakeLists.txt

@@ -106,13 +106,14 @@ if (LLVM_ENABLE_SPHINX)
         COMMAND "${CMAKE_COMMAND}" -E copy_directory
         "${CMAKE_CURRENT_SOURCE_DIR}"
         "${CMAKE_CURRENT_BINARY_DIR}/Source"
-
-        COMMAND "${CMAKE_COMMAND}" -E copy
-        "${CMAKE_CURRENT_BINARY_DIR}/Dialect/FIRLangRef.md"
-        "${CMAKE_CURRENT_BINARY_DIR}/Source/FIRLangRef.md"
-
         DEPENDS flang-doc)
 
+        # Runs a python script prior to HTML generation to prepend a header to FIRLangRef,
+        # Without the header, the page is incorrectly formatted, as it assumes the first entry is the page title.
+        add_custom_command(TARGET copy-flang-src-docs
+          COMMAND "${Python3_EXECUTABLE}"
+          ARGS ${CMAKE_CURRENT_BINARY_DIR}/Source/FIR/CreateFIRLangRef.py)
+
     endif()
     if (${SPHINX_OUTPUT_MAN})
       add_sphinx_target(man flang)

flang/docs/FIR/CreateFIRLangRef.py

@@ -0,0 +1,18 @@
+# This script combines FIRLangRef_Header.md with the auto-generated Dialect/FIRLangRef.md
+# for the purpose of creating an introduction header/paragraph for FIRLangRef.html
+
+# These paths are relative from the build directroy, not source, as that's where this tool is exectued.
+header_path = 'Source/FIR/FIRLangRef_Header.md'
+docs_path   = 'Dialect/FIRLangRef.md'
+output_path = 'Source/FIRLangRef.md'
+
+# 1. Writes line 1 from docs to output, (comment line that the file is autogenerated)
+# 2. Adds a new line
+# 3. Writes the entire header to the output file
+# 4. Writes the remainder of docs to the output file
+with open(output_path, 'w') as output:
+    with open(header_path, 'r') as header, open(docs_path, 'r') as docs:
+        output.write(docs.readline())
+        output.write("\n")
+        output.write(header.read())
+        output.write(docs.read())

flang/docs/FIR/FIRLangRef_Header.md

@@ -0,0 +1,3 @@
+# FIR Language Reference
+
+This page contains an overview of the Fortran IR operations, their syntax, and example usages.

flang/docs/_templates/indexsidebar.html

@@ -5,7 +5,6 @@
 
 <ul class="want-points">
     <li><a href="https://github.com/llvm/llvm-project/blob/main/flang/README.md#getting-started">Getting Started</a></li>
-    <li><a class="reference internal" href="FIRLangRef.html">Fortran IR Language Reference</a></li>
 </ul>
 
 <h3>Getting Involved</h3>

flang/docs/index.md

@@ -44,6 +44,7 @@ on how to get in touch with us and to learn more about the current status.
    Directives
    DoConcurrent
    Extensions
+   FIRLangRef
    FlangDriver
    FortranIR
    FortranLLVMTestSuite