[flang-commits] [flang] [Flang] Add Sphinx man page and html support for Flang (PR #141882)

[Tarun Prabhu via flang-commits]

================
@@ -105,32 +101,63 @@ endfunction()
 if (LLVM_ENABLE_SPHINX)
   include(AddSphinxTarget)
   if (SPHINX_FOUND)
-    if (${SPHINX_OUTPUT_HTML})
-      add_sphinx_target(html flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source")
 
-      add_dependencies(docs-flang-html copy-flang-src-docs)
+    # CLANG_TABLEGEN_EXE variable needs to be set for clang_tablegen to run without error
+    find_program(CLANG_TABLEGEN_EXE "clang-tblgen" ${LLVM_TOOLS_BINARY_DIR} NO_DEFAULT_PATH)
 
-      # 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"
-        DEPENDS flang-doc)
+    # Generate the RST file from TableGen (shared by both HTML and MAN builds)
+    gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs FlangOptionsDocs.td)
 
-      # 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
+    if (${SPHINX_OUTPUT_HTML})
+      message(STATUS "Using index.md for html build")
+
+      # Copy the entire flang/docs directory to the build Source dir,
+      # then remove the index.rst file, to avoid clash with index.md 
+      # which is used for the HTML build.
+      add_custom_target(copy-flang-src-docs-html
+        COMMAND "${CMAKE_COMMAND}" -E copy_directory
+              "${CMAKE_CURRENT_SOURCE_DIR}"
+              "${CMAKE_CURRENT_BINARY_DIR}/Source"
+        COMMAND "${CMAKE_COMMAND}" -E remove
+          "${CMAKE_CURRENT_BINARY_DIR}/Source/index.rst"
+        DEPENDS flang-doc gen-FlangCommandLineReference.rst)
+
+      # Run Python preprocessing ONLY for HTML build
+      # This script prepends headers to FIRLangRef.md for proper formatting
+      add_custom_command(TARGET copy-flang-src-docs-html
         COMMAND "${Python3_EXECUTABLE}"
         ARGS ${CMAKE_CURRENT_BINARY_DIR}/Source/FIR/CreateFIRLangRef.py)
 
-      # CLANG_TABLEGEN_EXE variable needs to be set for clang_tablegen to run without error
-      find_program(CLANG_TABLEGEN_EXE "clang-tblgen" ${LLVM_TOOLS_BINARY_DIR} NO_DEFAULT_PATH)
-      gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs FlangOptionsDocs.td docs-flang-html)
+      add_sphinx_target(html flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source")
+      add_dependencies(docs-flang-html copy-flang-src-docs-html)
     endif()
+
+    # ----------------------------
+    # MAN BUILD SETUP
+    # ----------------------------
     if (${SPHINX_OUTPUT_MAN})
-      add_sphinx_target(man flang)
+      message(STATUS "NOTE: The Flang man page is currently a placeholder with a TODO. See docs/index.rst for details")
+
+      # Create minimal Source dir with ONLY the files needed for man build:
+      # - conf.py (Sphinx config)
+      # - index.rst (top-level man page)
+      # - FlangCommandLineReference.rst (generated reference)
+      add_custom_target(copy-flang-src-docs-man
+        COMMAND "${CMAKE_COMMAND}" -E make_directory
+                "${CMAKE_CURRENT_BINARY_DIR}/Source"
+        COMMAND "${CMAKE_COMMAND}" -E copy
+          "${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
+          "${CMAKE_CURRENT_BINARY_DIR}/Source/conf.py"
+        COMMAND "${CMAKE_COMMAND}" -E copy
+                "${CMAKE_CURRENT_SOURCE_DIR}/index.rst"
+                "${CMAKE_CURRENT_BINARY_DIR}/Source/index.rst"
+        COMMAND "${CMAKE_COMMAND}" -E copy
+                "${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineReference.rst"
+                "${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineReference.rst"
----------------
tarunprabhu wrote:

Is this correct? Unless I am missing something, this seems to be copying the file onto itself

https://github.com/llvm/llvm-project/pull/141882