[Flang] Add a link from the docs html page to the FIR html page

[DylanFleming-arm]

Summary

The Fortran Language Reference is currently generated via tablegen,
however isn't present on flang.llvm.org/docs/

This patch adds FIRLangRef.md to the flang/docs directoy,
and adds a link to the generated HTML file in sidebar
under the 'Documentation' heading.

[kiranchandramohan]

The Fortran Language Reference is currently generated via tablegen, however isn't present on flang.llvm.org/docs/

Nit: Fortran IR (FIR) Language Reference

If the rendering for the first entry is not yet fixed, please call out that in the summary.

flang/docs/CMakeLists.txt

105

-> If we copy this into the top-level directory, will that automatically create an entry on the main page, besides the sidebar?
-> I was thinking we will be copying the *.md files in flang/docs somewhere in the Binary Directory and then we will build flang-doc target and then we will copy the FIRLangRef.md file to a sub-directory in the Binary directory. Usually copying generated files in the binary directory to the source directory is a good idea or not.

[kiranchandramohan]

flang/docs/CMakeLists.txt

105

I meant, that copying generated files to the source directory is generally not a good idea.

[awarzynski]

flang/docs/CMakeLists.txt

105

I agree, the source directory should not be modified during the CMake configuration or the build process.

[DylanFleming-arm]

Changed summary to include problem with incorrect formatting.
Removed copying of FIRLangRef to source.

[awarzynski]

You are making a change similar to https://reviews.llvm.org/D72875 - I would refer to that Clang patch (it explains, amongst other things, the requirement for copying things across). Could you also expand the comments to explain the need for copying files?

flang/docs/CMakeLists.txt

98–117

Is /Source at the end required?

[DylanFleming-arm]

Expanded comments around copying files.

The /Source is required, it defines the director where conf.py is located, it'll error without it.
While creating the directory itself isn't 100% necessary, there's multiple files/subdirectories
being copied so I think it's just cleaner to have them all in one directory, even if it does require that '/Source'

[kiranchandramohan]

Do we still have the requirement to build this twice? I got an error while clicking "FIR Language Reference". If it is solved by the python script, then is it better to merge D129186 into this?

[DylanFleming-arm]

Ah, I must've forgotten about that problem,

I've combined the copying of FIRLangRef.md and the src files into one custom target, which should now mean they both happen before html is generated.
That should fix the problem!

[kiranchandramohan]

flang/docs/CMakeLists.txt

100–101

Is there any guarantee on the order in which these dependencies are run?

114

What is the guarantee that at this point FIRLangRef.md is already generated?

[kiranchandramohan]

flang/docs/CMakeLists.txt

101

Does the following make sense?

Change

add_dependencies(docs-flang-html flang-doc)

to

add_dependencies(copy-flang-src-docs flang-doc)

and move it after add_custom_target(copy-flang-src-docs.

[DylanFleming-arm]

I've moved the dependency inside the custom_target declaration, it should resolve the issue of dependency ordering.

[kiranchandramohan]

LGTM. Have a Nit comment. Please address and submit.

flang/docs/CMakeLists.txt

105

Nit: Please rewrite this in a suitable manner. A suggestion given below.

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.

106

Nit: to the binary directory.

flang/docs/CMakeLists.txt

if (LLVM_ENABLE_DOXYGEN)
   endif()
 endif()
 endif()
 
 if (LLVM_ENABLE_SPHINX)
   include(AddSphinxTarget)
   if (SPHINX_FOUND)
     if (${SPHINX_OUTPUT_HTML})
-      add_sphinx_target(html flang)
+      add_sphinx_target(html flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source")
+
+      add_dependencies(docs-flang-html copy-flang-src-docs)
+
+      # Copies flang/docs/ and FIRLangRef.md to binary directory
+      # Sphinx requires all files to be in the same directory
+      # in order to process them into HTML, since FIRLangRef.md
+      # doesn't exist in src, the non-generated .md files need to be
+      # copied to the bin directory.
+      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)
+
     endif()
     if (${SPHINX_OUTPUT_MAN})
       add_sphinx_target(man flang)
     endif()
   endif()
 endif()
 

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>