[Flang] Fix formatting for FIRLangRef.html

[DylanFleming-arm]

Summary

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

[DylanFleming-arm]

Reworked CreateFIRLangRef.py to better fit pythons standards based upon internal review.

[kiranchandramohan]

flang/docs/FIR/CreateFIRLangRef.py

2

Do we need the path to the python executable here? Is this script expected to work if called from the command line with appropriate arguments?

Clang has the following for the scripts in docs/tools.

#!/usr/bin/env python3
# A tool to parse the FormatStyle struct from Format.h and update the
# documentation in ../ClangFormatStyleOptions.rst automatically.
# Run from the directory in which this file is located to update the docs.

[DylanFleming-arm]

I don't believe the path needs to be at the top here? I may be wrong but I think they're mainly for manual execution, This script should only realistically be ran as part of the HTML auto-generation process.
I've added a comment to the top of the file to explain it's purpose at least, I think that should be sufficient in this case.

[kiranchandramohan]

LGTM. Have some Nit comments. Please address and submit directly. Make sure you rebase correctly over the dependent patch.

flang/docs/FIR/CreateFIRLangRef.py

3

Nit: full-stop at the end.

5

Nit: spelling: directory

6–8

Nit: There seems to be a style to name variables holding paths with CAPS.
Nit: Will this work on Windows or do you have to use os.path.join?

[DylanFleming-arm]

Rebased onto main.

flang/docs/CMakeLists.txt

if (${SPHINX_OUTPUT_HTML})
 
       # Copy the flang/docs directory and the generated FIRLangRef.md file to a place in the binary directory.
       # Having all the files in a single directory makes it possible for Sphinx to process them together.
       # Add a dependency to the flang-doc target to ensure that the FIRLangRef.md file is generated before the copying happens.
       add_custom_target(copy-flang-src-docs
         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)
     endif()
   endif()
 endif()
 

flang/docs/FIR/CreateFIRLangRef.py

+# 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

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

flang/docs/_templates/indexsidebar.html

 {# This template defines sidebar which can be used to provide common links on
    all documentation pages. #}
 
 <h3>Documentation</h3>
 
 <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>
 <! TODO: Point links to website(flang.llvm.org) and not github once webpage comes up.>
 <ul class="want-points">
     <li><a href="https://github.com/llvm/llvm-project/blob/main/flang/docs/GettingInvolved.md#mailing-lists">Mailing Lists</a></li>
     <li><a href="https://github.com/llvm/llvm-project/blob/main/flang/docs/GettingInvolved.md#chat">Slack</a></li>
     <li><a href="https://github.com/llvm/llvm-project/blob/main/flang/docs/GettingInvolved.md#calls">Calls</a></li>

flang/docs/index.md

.. toctree::
    ArrayComposition
    BijectiveInternalNameUniquing
    Calls
    Character
    ControlFlowGraph
    Directives
    DoConcurrent
    Extensions
+   FIRLangRef
    FlangDriver
    FortranIR
    FortranLLVMTestSuite
    IORuntimeInternals
    Intrinsics
    LabelResolution
    ModFiles
    OpenMP-4.5-grammar.md