[flang-commits] [flang] [Flang] Add Sphinx man page support for Flang (PR #141882)
Samarth Narang via flang-commits
flang-commits at lists.llvm.org
Fri May 30 17:08:14 PDT 2025
https://github.com/snarang181 updated https://github.com/llvm/llvm-project/pull/141882
>From 7ef55e467fd2eaacc66c36c6e6e4df33b86ada62 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/5] [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 c21b5a0b7e404fc38f51f718e3f3c390d79af6a5 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/5] 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 925c666bd60163e4943a074689a5bbbcbe29614a 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/5] 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 56340f2b9b2f4f084033db919e9f1a727b621856 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/5] 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 cd886e1f1bc5a8fd46733a6f352faef4f1070dc0 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/5] 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
More information about the flang-commits
mailing list