[flang-commits] [flang] e7f05f2 - [Flang] Fix formatting for FIRLangRef.html

[Dylan Fleming via flang-commits]

Author: Dylan Fleming
Date: 2022-07-11T18:46:52Z
New Revision: e7f05f2ad3d70594619e6fd17e19ce401cf42623

URL: https://github.com/llvm/llvm-project/commit/e7f05f2ad3d70594619e6fd17e19ce401cf42623
DIFF: https://github.com/llvm/llvm-project/commit/e7f05f2ad3d70594619e6fd17e19ce401cf42623.diff

LOG: [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

Added: 
    flang/docs/FIR/CreateFIRLangRef.py
    flang/docs/FIR/FIRLangRef_Header.md

Modified: 
    flang/docs/CMakeLists.txt
    flang/docs/_templates/indexsidebar.html
    flang/docs/index.md

Removed: 
    


################################################################################
diff  --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt
index 374bdf30cfbf7..044697a104507 100644
--- a/flang/docs/CMakeLists.txt
+++ b/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)

diff  --git a/flang/docs/FIR/CreateFIRLangRef.py b/flang/docs/FIR/CreateFIRLangRef.py
new file mode 100644
index 0000000000000..397163c702d73
--- /dev/null
+++ b/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())

diff  --git a/flang/docs/FIR/FIRLangRef_Header.md b/flang/docs/FIR/FIRLangRef_Header.md
new file mode 100644
index 0000000000000..04df60ed4eb39
--- /dev/null
+++ b/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.

diff  --git a/flang/docs/_templates/indexsidebar.html b/flang/docs/_templates/indexsidebar.html
index d06ada300969e..b6f7942e46bdd 100644
--- a/flang/docs/_templates/indexsidebar.html
+++ b/flang/docs/_templates/indexsidebar.html
@@ -5,7 +5,6 @@ <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>

diff  --git a/flang/docs/index.md b/flang/docs/index.md
index 555c0ccdb1437..a12c98ad08631 100644
--- a/flang/docs/index.md
+++ b/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