From 6ae86c3c2b51231e26d37ac1b71390f75c5b01ef Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Wed, 28 May 2025 20:21:16 -0400 Subject: [PATCH 01/18] [Flang][Docs] Add Sphinx man page support for Flang This patch enables building Flang man pages by: - Adding a `man_pages` entry in flang/docs/conf.py for Sphinx man builder. - Adding a minimal `index.rst` as the master document. - Adding placeholder `.rst` files for FIRLangRef and FlangCommandLineReference to fix toctree references. These changes unblock builds using `-DLLVM_BUILD_MANPAGES=ON` and allow `ninja docs-flang-man` to generate `flang.1`. Fixes #141757 --- flang/docs/FIRLangRef.rst | 4 ++++ flang/docs/FlangCommandLineReference.rst | 4 ++++ flang/docs/conf.py | 4 +++- flang/docs/index.rst | 10 ++++++++++ 4 files changed, 21 insertions(+), 1 deletion(-) create mode 100644 flang/docs/FIRLangRef.rst create mode 100644 flang/docs/FlangCommandLineReference.rst create mode 100644 flang/docs/index.rst diff --git a/flang/docs/FIRLangRef.rst b/flang/docs/FIRLangRef.rst new file mode 100644 index 0000000000000..91edd67fdcad8 --- /dev/null +++ b/flang/docs/FIRLangRef.rst @@ -0,0 +1,4 @@ +FIR Language Reference +====================== + +(TODO: Add FIR language reference documentation) diff --git a/flang/docs/FlangCommandLineReference.rst b/flang/docs/FlangCommandLineReference.rst new file mode 100644 index 0000000000000..71f77f28ba72c --- /dev/null +++ b/flang/docs/FlangCommandLineReference.rst @@ -0,0 +1,4 @@ +Flang Command Line Reference +============================ + +(TODO: Add Flang CLI documentation) diff --git a/flang/docs/conf.py b/flang/docs/conf.py index 48f7b69f5d750..46907f144e25a 100644 --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -227,7 +227,9 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [] +man_pages = [ + ('index', 'flang', 'Flang Documentation', ['Flang Contributors'], 1) +] # If true, show URL addresses after external links. # man_show_urls = False diff --git a/flang/docs/index.rst b/flang/docs/index.rst new file mode 100644 index 0000000000000..09677eb87704f --- /dev/null +++ b/flang/docs/index.rst @@ -0,0 +1,10 @@ +Flang Documentation +==================== + +Welcome to the Flang documentation. + +.. toctree:: + :maxdepth: 1 + + FIRLangRef + FlangCommandLineReference From ee8b467b66c924b0030fe6307309df013e95ac13 Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Thu, 29 May 2025 06:53:34 -0400 Subject: [PATCH 02/18] Remove .rst files and point conf.py to pick up .md --- flang/docs/FIRLangRef.rst | 4 ---- flang/docs/FlangCommandLineReference.rst | 4 ---- flang/docs/conf.py | 5 ++--- flang/docs/index.rst | 10 ---------- 4 files changed, 2 insertions(+), 21 deletions(-) delete mode 100644 flang/docs/FIRLangRef.rst delete mode 100644 flang/docs/FlangCommandLineReference.rst delete mode 100644 flang/docs/index.rst diff --git a/flang/docs/FIRLangRef.rst b/flang/docs/FIRLangRef.rst deleted file mode 100644 index 91edd67fdcad8..0000000000000 --- a/flang/docs/FIRLangRef.rst +++ /dev/null @@ -1,4 +0,0 @@ -FIR Language Reference -====================== - -(TODO: Add FIR language reference documentation) diff --git a/flang/docs/FlangCommandLineReference.rst b/flang/docs/FlangCommandLineReference.rst deleted file mode 100644 index 71f77f28ba72c..0000000000000 --- a/flang/docs/FlangCommandLineReference.rst +++ /dev/null @@ -1,4 +0,0 @@ -Flang Command Line Reference -============================ - -(TODO: Add Flang CLI documentation) diff --git a/flang/docs/conf.py b/flang/docs/conf.py index 46907f144e25a..4fd81440c8176 100644 --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -42,6 +42,7 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] +source_suffix = [".md"] myst_heading_anchors = 6 import sphinx @@ -227,9 +228,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'flang', 'Flang Documentation', ['Flang Contributors'], 1) -] +man_pages = [("index", "flang", "Flang Documentation", ["Flang Contributors"], 1)] # If true, show URL addresses after external links. # man_show_urls = False diff --git a/flang/docs/index.rst b/flang/docs/index.rst deleted file mode 100644 index 09677eb87704f..0000000000000 --- a/flang/docs/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Flang Documentation -==================== - -Welcome to the Flang documentation. - -.. toctree:: - :maxdepth: 1 - - FIRLangRef - FlangCommandLineReference From 8931a4caccdfc2eea865a2fec7e6692c72e21573 Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Thu, 29 May 2025 07:03:35 -0400 Subject: [PATCH 03/18] While building man pages, the .md files were being used. Due to that, the myst_parser was explictly imported. Adding Placeholder .md files which are required by index.md --- flang/docs/FIRLangRef.md | 3 +++ flang/docs/FlangCommandLineReference.md | 3 +++ flang/docs/conf.py | 10 +++++----- 3 files changed, 11 insertions(+), 5 deletions(-) create mode 100644 flang/docs/FIRLangRef.md create mode 100644 flang/docs/FlangCommandLineReference.md diff --git a/flang/docs/FIRLangRef.md b/flang/docs/FIRLangRef.md new file mode 100644 index 0000000000000..8e4052f14fc7c --- /dev/null +++ b/flang/docs/FIRLangRef.md @@ -0,0 +1,3 @@ +# FIR Language Reference + +_TODO: Add FIR language reference documentation._ diff --git a/flang/docs/FlangCommandLineReference.md b/flang/docs/FlangCommandLineReference.md new file mode 100644 index 0000000000000..ee8d7b83dc50c --- /dev/null +++ b/flang/docs/FlangCommandLineReference.md @@ -0,0 +1,3 @@ +# Flang Command Line Reference + +_TODO: Add Flang CLI documentation._ diff --git a/flang/docs/conf.py b/flang/docs/conf.py index 4fd81440c8176..7223661625689 100644 --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -10,6 +10,7 @@ # serve to show the default. from datetime import date + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -28,16 +29,15 @@ "sphinx.ext.autodoc", ] -# When building man pages, we do not use the markdown pages, -# So, we can continue without the myst_parser dependencies. -# Doing so reduces dependencies of some packaged llvm distributions. + try: import myst_parser extensions.append("myst_parser") except ImportError: - if not tags.has("builder-man"): - raise + raise ImportError( + "myst_parser is required to build documentation, including man pages." + ) # Add any paths that contain templates here, relative to this directory. From a05f24bb6b919b3e578e45e416dce681afde50ec Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Thu, 29 May 2025 09:01:22 -0400 Subject: [PATCH 04/18] Remove placeholder .md files --- flang/docs/FIRLangRef.md | 3 --- flang/docs/FlangCommandLineReference.md | 3 --- 2 files changed, 6 deletions(-) delete mode 100644 flang/docs/FIRLangRef.md delete mode 100644 flang/docs/FlangCommandLineReference.md diff --git a/flang/docs/FIRLangRef.md b/flang/docs/FIRLangRef.md deleted file mode 100644 index 8e4052f14fc7c..0000000000000 --- a/flang/docs/FIRLangRef.md +++ /dev/null @@ -1,3 +0,0 @@ -# FIR Language Reference - -_TODO: Add FIR language reference documentation._ diff --git a/flang/docs/FlangCommandLineReference.md b/flang/docs/FlangCommandLineReference.md deleted file mode 100644 index ee8d7b83dc50c..0000000000000 --- a/flang/docs/FlangCommandLineReference.md +++ /dev/null @@ -1,3 +0,0 @@ -# Flang Command Line Reference - -_TODO: Add Flang CLI documentation._ From 83df5732c8dd6a0709098e04d0110d32d1d65694 Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Fri, 30 May 2025 14:10:36 -0400 Subject: [PATCH 05/18] Enable docs-flang-html to build --- flang/docs/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/flang/docs/conf.py b/flang/docs/conf.py index 7223661625689..03f5973392d65 100644 --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -42,7 +42,10 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] -source_suffix = [".md"] +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} myst_heading_anchors = 6 import sphinx From 86be72803ade35f3bd436bf2816c5d2b5be309cf Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Fri, 30 May 2025 20:32:33 -0400 Subject: [PATCH 06/18] Modify CMake to build man without warnings --- flang/docs/CMakeLists.txt | 50 +++++++++++++++++++-------------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index 92feb059d4caa..e60f89569dad3 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -82,7 +82,7 @@ if (LLVM_ENABLE_DOXYGEN) endif() endif() -function (gen_rst_file_from_td output_file td_option source docs_target) +function (gen_rst_file_from_td output_file td_option source) if (NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${source}") message(FATAL_ERROR "Cannot find source file: ${source} in ${CMAKE_CURRENT_SOURCE_DIR}") endif() @@ -90,8 +90,6 @@ function (gen_rst_file_from_td output_file td_option source docs_target) list(APPEND LLVM_TABLEGEN_FLAGS "-I${TABLEGEN_INCLUDE_DIR}") list(APPEND LLVM_TABLEGEN_FLAGS "-I${CMAKE_CURRENT_SOURCE_DIR}/../../clang/include/clang/Driver/") clang_tablegen(Source/${output_file} ${td_option} SOURCE ${source} TARGET "gen-${output_file}") - add_dependencies(${docs_target} "gen-${output_file}") - # clang_tablegen() does not create the output directory automatically, # so we have to create it explicitly. Note that copy-flang-src-docs below # does create the output directory, but it is not necessarily run @@ -105,32 +103,34 @@ endfunction() if (LLVM_ENABLE_SPHINX) include(AddSphinxTarget) if (SPHINX_FOUND) + + # 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) + + # 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) + + # 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 gen-FlangCommandLineReference.rst) + + # Run Python preprocessing to prepend header to FIRLangRef.md + add_custom_command(TARGET copy-flang-src-docs + COMMAND "${Python3_EXECUTABLE}" + ARGS ${CMAKE_CURRENT_BINARY_DIR}/Source/FIR/CreateFIRLangRef.py) + 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) - - # 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) - - # 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) - - # 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) endif() if (${SPHINX_OUTPUT_MAN}) - add_sphinx_target(man flang) + add_sphinx_target(man flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") + add_dependencies(docs-flang-man gen-FlangCommandLineReference.rst) + add_dependencies(docs-flang-man copy-flang-src-docs) endif() endif() endif() From b4573984a6a4c7dc797fd1e4f4fd40fce811e53e Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Fri, 30 May 2025 20:44:17 -0400 Subject: [PATCH 07/18] Minor fix for building html version copy-flang-src-docs builds Source/ directory and in fixing, did not include it in the HTML target deps --- flang/docs/CMakeLists.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index e60f89569dad3..2737d08c83196 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -126,6 +126,7 @@ if (LLVM_ENABLE_SPHINX) 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) endif() if (${SPHINX_OUTPUT_MAN}) add_sphinx_target(man flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") From 6908acea42d35981060d72fc7b402709143330ce Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Mon, 2 Jun 2025 06:25:55 -0400 Subject: [PATCH 08/18] Remove redundant dependence in CMake config --- flang/docs/CMakeLists.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index 2737d08c83196..27979f0688deb 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -130,7 +130,6 @@ if (LLVM_ENABLE_SPHINX) endif() if (${SPHINX_OUTPUT_MAN}) add_sphinx_target(man flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") - add_dependencies(docs-flang-man gen-FlangCommandLineReference.rst) add_dependencies(docs-flang-man copy-flang-src-docs) endif() endif() From 418c89d38566198c0eeb7cfa61548f9a99c97fff Mon Sep 17 00:00:00 2001 From: "Narang, Samarth" Date: Mon, 2 Jun 2025 16:59:23 -0400 Subject: [PATCH 09/18] Add Placeholder man page template for flang docs --- flang/docs/CMakeLists.txt | 1 + flang/docs/conf.py | 2 +- flang/docs/index.rst | 11 +++++++++++ 3 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 flang/docs/index.rst diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index 27979f0688deb..4eb16c5f89513 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -129,6 +129,7 @@ if (LLVM_ENABLE_SPHINX) add_dependencies(docs-flang-html copy-flang-src-docs) endif() if (${SPHINX_OUTPUT_MAN}) + message(STATUS "NOTE: The Flang man page is currently a placeholder with a TODO. See docs/index.rst for details") add_sphinx_target(man flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") add_dependencies(docs-flang-man copy-flang-src-docs) endif() diff --git a/flang/docs/conf.py b/flang/docs/conf.py index 03f5973392d65..3930ec9da5d7d 100644 --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -231,7 +231,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [("index", "flang", "Flang Documentation", ["Flang Contributors"], 1)] +man_pages = [("index", "flang", "Flang Documentation (In Progress)", ["Flang Contributors"], 1)] # If true, show URL addresses after external links. # man_show_urls = False diff --git a/flang/docs/index.rst b/flang/docs/index.rst new file mode 100644 index 0000000000000..1c38cc8eb5077 --- /dev/null +++ b/flang/docs/index.rst @@ -0,0 +1,11 @@ +Flang Manual Page (In Progress) +================================================== + +.. note:: + This man page is under development. + +For full documentation, please see the online HTML docs: + +https://flang.llvm.org/docs/FlangCommandLineReference.html + +TODO: Replace this placeholder with finalized man page content. \ No newline at end of file From 25fc2860eac1ba6fd0985797fed58f295a7240c9 Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Mon, 2 Jun 2025 20:29:15 -0400 Subject: [PATCH 10/18] Modify CMake to support man page build Separate html and man page builds in CMakeLists.txt --- flang/docs/CMakeLists.txt | 64 +++++++++++++++++++++++++++------------ flang/docs/conf.py | 10 +++++- flang/docs/index.rst | 14 +++++++-- 3 files changed, 66 insertions(+), 22 deletions(-) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index 4eb16c5f89513..bdf9feb7836b6 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -91,9 +91,7 @@ function (gen_rst_file_from_td output_file td_option source) list(APPEND LLVM_TABLEGEN_FLAGS "-I${CMAKE_CURRENT_SOURCE_DIR}/../../clang/include/clang/Driver/") clang_tablegen(Source/${output_file} ${td_option} SOURCE ${source} TARGET "gen-${output_file}") # clang_tablegen() does not create the output directory automatically, - # so we have to create it explicitly. Note that copy-flang-src-docs below - # does create the output directory, but it is not necessarily run - # before RST generation. + # so we have to create it explicitly. add_custom_target(create-flang-rst-output-dir COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/Source ) @@ -110,28 +108,56 @@ if (LLVM_ENABLE_SPHINX) # 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) - # 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 gen-FlangCommandLineReference.rst) - - # Run Python preprocessing to prepend header to FIRLangRef.md - add_custom_command(TARGET copy-flang-src-docs - COMMAND "${Python3_EXECUTABLE}" - ARGS ${CMAKE_CURRENT_BINARY_DIR}/Source/FIR/CreateFIRLangRef.py) - 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) + add_sphinx_target(html flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") - add_dependencies(docs-flang-html copy-flang-src-docs) + add_dependencies(docs-flang-html copy-flang-src-docs-html) endif() + + # ---------------------------- + # MAN BUILD SETUP + # ---------------------------- if (${SPHINX_OUTPUT_MAN}) 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" + DEPENDS flang-doc gen-FlangCommandLineReference.rst) + add_sphinx_target(man flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") - add_dependencies(docs-flang-man copy-flang-src-docs) + add_dependencies(docs-flang-man copy-flang-src-docs-man) endif() endif() endif() diff --git a/flang/docs/conf.py b/flang/docs/conf.py index 3930ec9da5d7d..7cd91437d25b0 100644 --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -231,7 +231,15 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [("index", "flang", "Flang Documentation (In Progress)", ["Flang Contributors"], 1)] +man_pages = [ + ( + "index", + "flang", + "Flang Documentation (In Progress)", + ["Flang Contributors"], + 1, + ) +] # If true, show URL addresses after external links. # man_show_urls = False diff --git a/flang/docs/index.rst b/flang/docs/index.rst index 1c38cc8eb5077..1138edf16278b 100644 --- a/flang/docs/index.rst +++ b/flang/docs/index.rst @@ -6,6 +6,16 @@ Flang Manual Page (In Progress) For full documentation, please see the online HTML docs: -https://flang.llvm.org/docs/FlangCommandLineReference.html +https://flang.llvm.org/docs/ -TODO: Replace this placeholder with finalized man page content. \ No newline at end of file +TODO: This man page currently shows FlangCommandLineReference this with finalized man page content. + +---- + +Flang Command Line Reference +---------------------------- + +.. toctree:: + :maxdepth: 1 + + FlangCommandLineReference From 7483f8d26d18abb0dbe8f2f5edb5a3a55abe8709 Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Tue, 3 Jun 2025 13:00:33 -0400 Subject: [PATCH 11/18] Address suggestions --- flang/docs/conf.py | 2 -- flang/docs/index.rst | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/flang/docs/conf.py b/flang/docs/conf.py index 7cd91437d25b0..a470d8afd7186 100644 --- a/flang/docs/conf.py +++ b/flang/docs/conf.py @@ -10,7 +10,6 @@ # serve to show the default. from datetime import date - # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -29,7 +28,6 @@ "sphinx.ext.autodoc", ] - try: import myst_parser diff --git a/flang/docs/index.rst b/flang/docs/index.rst index 1138edf16278b..ff74b3f1644ce 100644 --- a/flang/docs/index.rst +++ b/flang/docs/index.rst @@ -8,7 +8,7 @@ For full documentation, please see the online HTML docs: https://flang.llvm.org/docs/ -TODO: This man page currently shows FlangCommandLineReference this with finalized man page content. +TODO: This man page currently shows FlangCommandLineReference, will be ultimately replaced with finalized man page content. ---- From 737c725f9546af12490cf1c4181aef2c9feedf51 Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Tue, 3 Jun 2025 15:01:29 -0400 Subject: [PATCH 12/18] Remove redundant command in CMake Modify man page doc --- flang/docs/CMakeLists.txt | 3 --- flang/docs/index.rst | 3 ++- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index bdf9feb7836b6..4a4d72961f6bb 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -151,9 +151,6 @@ if (LLVM_ENABLE_SPHINX) 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" DEPENDS flang-doc gen-FlangCommandLineReference.rst) add_sphinx_target(man flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") diff --git a/flang/docs/index.rst b/flang/docs/index.rst index ff74b3f1644ce..093c79fa185be 100644 --- a/flang/docs/index.rst +++ b/flang/docs/index.rst @@ -8,7 +8,8 @@ For full documentation, please see the online HTML docs: https://flang.llvm.org/docs/ -TODO: This man page currently shows FlangCommandLineReference, will be ultimately replaced with finalized man page content. +.. + The placeholder text "FlangCommandLineReference" below should eventually be replaced with the actual man page contents. ---- From 0f256db87af7a56c5097e583141bc36251b76e8b Mon Sep 17 00:00:00 2001 From: "Narang, Samarth" Date: Wed, 4 Jun 2025 10:10:30 -0400 Subject: [PATCH 13/18] Move index.rst to docs/CommandGuide --- flang/docs/CMakeLists.txt | 4 ++-- flang/docs/{ => CommandGuide}/index.rst | 0 2 files changed, 2 insertions(+), 2 deletions(-) rename flang/docs/{ => CommandGuide}/index.rst (100%) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index 4a4d72961f6bb..9a56f9bb51973 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -136,7 +136,7 @@ if (LLVM_ENABLE_SPHINX) # MAN BUILD SETUP # ---------------------------- if (${SPHINX_OUTPUT_MAN}) - message(STATUS "NOTE: The Flang man page is currently a placeholder with a TODO. See docs/index.rst for details") + message(STATUS "NOTE: The Flang man page is currently a placeholder with a TODO. See docs/CommandGuide/index.rst for details") # Create minimal Source dir with ONLY the files needed for man build: # - conf.py (Sphinx config) @@ -149,7 +149,7 @@ if (LLVM_ENABLE_SPHINX) "${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_SOURCE_DIR}/CommandGuide/index.rst" "${CMAKE_CURRENT_BINARY_DIR}/Source/index.rst" DEPENDS flang-doc gen-FlangCommandLineReference.rst) diff --git a/flang/docs/index.rst b/flang/docs/CommandGuide/index.rst similarity index 100% rename from flang/docs/index.rst rename to flang/docs/CommandGuide/index.rst From 149036a0a35ff1b486d6a64aa5f24a5df2867235 Mon Sep 17 00:00:00 2001 From: "Narang, Samarth" Date: Wed, 4 Jun 2025 10:18:39 -0400 Subject: [PATCH 14/18] Adjust path to CommandLineReference file --- flang/docs/CommandGuide/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/flang/docs/CommandGuide/index.rst b/flang/docs/CommandGuide/index.rst index 093c79fa185be..81a0196dccf79 100644 --- a/flang/docs/CommandGuide/index.rst +++ b/flang/docs/CommandGuide/index.rst @@ -19,4 +19,4 @@ Flang Command Line Reference .. toctree:: :maxdepth: 1 - FlangCommandLineReference + ../FlangCommandLineReference From ef6fa3716bee60cf4314da98bf5a46469fbc7d9b Mon Sep 17 00:00:00 2001 From: "Narang, Samarth" Date: Wed, 4 Jun 2025 11:03:08 -0400 Subject: [PATCH 15/18] relative path change in removing of CommandLineGuide --- flang/docs/CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index 9a56f9bb51973..485fba3e5fc5f 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -119,7 +119,7 @@ if (LLVM_ENABLE_SPHINX) "${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}/Source" COMMAND "${CMAKE_COMMAND}" -E remove - "${CMAKE_CURRENT_BINARY_DIR}/Source/index.rst" + "${CMAKE_CURRENT_BINARY_DIR}/Source/CommandGuide/index.rst" DEPENDS flang-doc gen-FlangCommandLineReference.rst) # Run Python preprocessing ONLY for HTML build From 0c24894a95298186e3de8a38333005bf255ee301 Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Wed, 4 Jun 2025 10:13:48 -0700 Subject: [PATCH 16/18] Separate out build directories for man and html builds --- flang/docs/CMakeLists.txt | 21 +++++++++++++-------- flang/docs/CommandGuide/index.rst | 2 +- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index 485fba3e5fc5f..277d27de6a4ac 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -99,6 +99,8 @@ function (gen_rst_file_from_td output_file td_option source) endfunction() if (LLVM_ENABLE_SPHINX) + set (FLANG_DOCS_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/SourceHtml") + set (FLANG_DOCS_MAN_DIR "${CMAKE_CURRENT_BINARY_DIR}/SourceMan") include(AddSphinxTarget) if (SPHINX_FOUND) @@ -117,18 +119,18 @@ if (LLVM_ENABLE_SPHINX) add_custom_target(copy-flang-src-docs-html COMMAND "${CMAKE_COMMAND}" -E copy_directory "${CMAKE_CURRENT_SOURCE_DIR}" - "${CMAKE_CURRENT_BINARY_DIR}/Source" + "${FLANG_DOCS_HTML_DIR}" COMMAND "${CMAKE_COMMAND}" -E remove - "${CMAKE_CURRENT_BINARY_DIR}/Source/CommandGuide/index.rst" + "${FLANG_DOCS_HTML_DIR}/CommandGuide/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) + ARGS "${FLANG_DOCS_HTML_DIR}/FIR/CreateFIRLangRef.py") - add_sphinx_target(html flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") + add_sphinx_target(html flang SOURCE_DIR "${FLANG_DOCS_HTML_DIR}") add_dependencies(docs-flang-html copy-flang-src-docs-html) endif() @@ -144,16 +146,19 @@ if (LLVM_ENABLE_SPHINX) # - FlangCommandLineReference.rst (generated reference) add_custom_target(copy-flang-src-docs-man COMMAND "${CMAKE_COMMAND}" -E make_directory - "${CMAKE_CURRENT_BINARY_DIR}/Source" + "${FLANG_DOCS_MAN_DIR}" COMMAND "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/conf.py" - "${CMAKE_CURRENT_BINARY_DIR}/Source/conf.py" + "${FLANG_DOCS_MAN_DIR}/conf.py" + COMMAND "${CMAKE_COMMAND}" -E copy + "${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineReference.rst" + "${FLANG_DOCS_MAN_DIR}/FlangCommandLineReference.rst" COMMAND "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/CommandGuide/index.rst" - "${CMAKE_CURRENT_BINARY_DIR}/Source/index.rst" + "${FLANG_DOCS_MAN_DIR}/index.rst" DEPENDS flang-doc gen-FlangCommandLineReference.rst) - add_sphinx_target(man flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source") + add_sphinx_target(man flang SOURCE_DIR "${FLANG_DOCS_MAN_DIR}") add_dependencies(docs-flang-man copy-flang-src-docs-man) endif() endif() diff --git a/flang/docs/CommandGuide/index.rst b/flang/docs/CommandGuide/index.rst index 81a0196dccf79..093c79fa185be 100644 --- a/flang/docs/CommandGuide/index.rst +++ b/flang/docs/CommandGuide/index.rst @@ -19,4 +19,4 @@ Flang Command Line Reference .. toctree:: :maxdepth: 1 - ../FlangCommandLineReference + FlangCommandLineReference From b1ef91585d9ca0aa7d160293842084d59454f80d Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Wed, 4 Jun 2025 10:17:52 -0700 Subject: [PATCH 17/18] Modify build script to use HTML routes --- flang/docs/FIR/CreateFIRLangRef.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/flang/docs/FIR/CreateFIRLangRef.py b/flang/docs/FIR/CreateFIRLangRef.py index b6077364cdee6..803cd9da3f127 100644 --- a/flang/docs/FIR/CreateFIRLangRef.py +++ b/flang/docs/FIR/CreateFIRLangRef.py @@ -4,9 +4,9 @@ import os # These paths are relative to flang/docs in the build directory, not source, as that's where this tool is executed. -HEADER_PATH = os.path.join("Source", "FIR", "FIRLangRef_Header.md") +HEADER_PATH = os.path.join("SourceHtml", "FIR", "FIRLangRef_Header.md") DOCS_PATH = os.path.join("Dialect", "FIRLangRef.md") -OUTPUT_PATH = os.path.join("Source", "FIRLangRef.md") +OUTPUT_PATH = os.path.join("SourceHtml", "FIRLangRef.md") # 1. Writes line 1 from docs to output, (comment line that the file is autogenerated) # 2. Adds a new line From 4eee2e88de0aa7fd244fc1471b60e277c9363c60 Mon Sep 17 00:00:00 2001 From: Samarth Narang Date: Wed, 4 Jun 2025 10:27:18 -0700 Subject: [PATCH 18/18] Explicitly copy generated rst file for HTML build --- flang/docs/CMakeLists.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt index 277d27de6a4ac..a9f5811fcd064 100644 --- a/flang/docs/CMakeLists.txt +++ b/flang/docs/CMakeLists.txt @@ -122,6 +122,9 @@ if (LLVM_ENABLE_SPHINX) "${FLANG_DOCS_HTML_DIR}" COMMAND "${CMAKE_COMMAND}" -E remove "${FLANG_DOCS_HTML_DIR}/CommandGuide/index.rst" + COMMAND "${CMAKE_COMMAND}" -E copy + "${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineReference.rst" + "${FLANG_DOCS_HTML_DIR}/FlangCommandLineReference.rst" DEPENDS flang-doc gen-FlangCommandLineReference.rst) # Run Python preprocessing ONLY for HTML build