[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
Mon Jun 2 03:26:58 PDT 2025
https://github.com/snarang181 updated https://github.com/llvm/llvm-project/pull/141882
>From acb00472d49c3251287377892fbba1982b50f5d4 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 1/8] [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 c047a5f124217c968c6e4e9ff8de624da4408f6b 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 2/8] 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 d4debad800c8f363a6759c1ae1b2abb07066b615 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 3/8] 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 a1b5a911f2de3717073c70a1fc832b0df87994eb 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 4/8] 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 516891a88ba60baeefe90a029374b6b3919405c1 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 5/8] 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 c19cd509b2f1c8d8d03c873d2a512a47aec0a6c8 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 6/8] 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 20120a1497b0bbb431c46f81a4d371e89e3ab192 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 7/8] 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 b94047e821066a1c9ac8b55bbc602062ae817b0f 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 8/8] 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()
More information about the flang-commits
mailing list