[flang-commits] [flang] [Flang] Add Sphinx man page and html support for Flang (PR #141882)
Samarth Narang via flang-commits
flang-commits at lists.llvm.org
Wed Jun 4 08:03:56 PDT 2025
https://github.com/snarang181 updated https://github.com/llvm/llvm-project/pull/141882
>From 6ae86c3c2b51231e26d37ac1b71390f75c5b01ef Mon Sep 17 00:00:00 2001
From: Samarth Narang <snarang at umass.edu>
Date: Wed, 28 May 2025 20:21:16 -0400
Subject: [PATCH 01/15] [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 <snarang at umass.edu>
Date: Thu, 29 May 2025 06:53:34 -0400
Subject: [PATCH 02/15] 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 <snarang at umass.edu>
Date: Thu, 29 May 2025 07:03:35 -0400
Subject: [PATCH 03/15] 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 <snarang at umass.edu>
Date: Thu, 29 May 2025 09:01:22 -0400
Subject: [PATCH 04/15] 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 <snarang at umass.edu>
Date: Fri, 30 May 2025 14:10:36 -0400
Subject: [PATCH 05/15] 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 <snarang at umass.edu>
Date: Fri, 30 May 2025 20:32:33 -0400
Subject: [PATCH 06/15] 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 <snarang at umass.edu>
Date: Fri, 30 May 2025 20:44:17 -0400
Subject: [PATCH 07/15] 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 <snarang at umass.edu>
Date: Mon, 2 Jun 2025 06:25:55 -0400
Subject: [PATCH 08/15] 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" <snarang at utexas.edu>
Date: Mon, 2 Jun 2025 16:59:23 -0400
Subject: [PATCH 09/15] 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 <snarang at umass.edu>
Date: Mon, 2 Jun 2025 20:29:15 -0400
Subject: [PATCH 10/15] 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 <snarang at umass.edu>
Date: Tue, 3 Jun 2025 13:00:33 -0400
Subject: [PATCH 11/15] 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 <snarang at umass.edu>
Date: Tue, 3 Jun 2025 15:01:29 -0400
Subject: [PATCH 12/15] 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" <snarang at utexas.edu>
Date: Wed, 4 Jun 2025 10:10:30 -0400
Subject: [PATCH 13/15] 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" <snarang at utexas.edu>
Date: Wed, 4 Jun 2025 10:18:39 -0400
Subject: [PATCH 14/15] 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" <snarang at utexas.edu>
Date: Wed, 4 Jun 2025 11:03:08 -0400
Subject: [PATCH 15/15] 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
More information about the flang-commits
mailing list