Skip to content

Commit 47171ac

Browse files
snarang181snarang181
authored
[Flang] Add Sphinx man page and html support for Flang (#141882)
This patch refactors the Flang documentation CMake and Sphinx configuration to address build issues. **CMake changes**: - Moves the `gen_rst_file_from_td()` call out of the HTML-only block so that both `docs-flang-html` and `docs-flang-man` builds depend on the generated `FlangCommandLineReference.rst` file. **conf.py changes**: - Introduces `myst_parser` dependency as a required Markdown parser for both HTML and man builds. - Introduces the correct source_suffix mapping for both .rst and .md files. - Populates the man_pages configuration so the main index page generates a ` flang(1) `man page. Fixes #141757 --------- Authored-by: Samarth Narang <[email protected]>
1 parent 8d187e5 commit 47171ac

File tree

4 files changed

+97
-33
lines changed

4 files changed

+97
-33
lines changed

‎flang/docs/CMakeLists.txt

Lines changed: 57 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -82,55 +82,87 @@ if (LLVM_ENABLE_DOXYGEN)
8282
endif()
8383
endif()
8484

85-
function (gen_rst_file_from_td output_file td_option source docs_target)
85+
function (gen_rst_file_from_td output_file td_option source)
8686
if (NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${source}")
8787
message(FATAL_ERROR "Cannot find source file: ${source} in ${CMAKE_CURRENT_SOURCE_DIR}")
8888
endif()
8989
get_filename_component(TABLEGEN_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${source}" DIRECTORY)
9090
list(APPEND LLVM_TABLEGEN_FLAGS "-I${TABLEGEN_INCLUDE_DIR}")
9191
list(APPEND LLVM_TABLEGEN_FLAGS "-I${CMAKE_CURRENT_SOURCE_DIR}/../../clang/include/clang/Driver/")
9292
clang_tablegen(Source/${output_file} ${td_option} SOURCE ${source} TARGET "gen-${output_file}")
93-
add_dependencies(${docs_target} "gen-${output_file}")
94-
9593
# clang_tablegen() does not create the output directory automatically,
96-
# so we have to create it explicitly. Note that copy-flang-src-docs below
97-
# does create the output directory, but it is not necessarily run
98-
# before RST generation.
94+
# so we have to create it explicitly.
9995
add_custom_target(create-flang-rst-output-dir
10096
COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/Source
10197
)
10298
add_dependencies("gen-${output_file}" create-flang-rst-output-dir)
10399
endfunction()
104100

105101
if (LLVM_ENABLE_SPHINX)
102+
set (FLANG_DOCS_HTML_DIR "${CMAKE_CURRENT_BINARY_DIR}/SourceHtml")
103+
set (FLANG_DOCS_MAN_DIR "${CMAKE_CURRENT_BINARY_DIR}/SourceMan")
106104
include(AddSphinxTarget)
107105
if (SPHINX_FOUND)
108-
if (${SPHINX_OUTPUT_HTML})
109-
add_sphinx_target(html flang SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/Source")
110106

111-
add_dependencies(docs-flang-html copy-flang-src-docs)
107+
# CLANG_TABLEGEN_EXE variable needs to be set for clang_tablegen to run without error
108+
find_program(CLANG_TABLEGEN_EXE "clang-tblgen" ${LLVM_TOOLS_BINARY_DIR} NO_DEFAULT_PATH)
112109

113-
# Copy the flang/docs directory and the generated FIRLangRef.md file to a place in the binary directory.
114-
# Having all the files in a single directory makes it possible for Sphinx to process them together.
115-
# Add a dependency to the flang-doc target to ensure that the FIRLangRef.md file is generated before the copying happens.
116-
add_custom_target(copy-flang-src-docs
117-
COMMAND "${CMAKE_COMMAND}" -E copy_directory
118-
"${CMAKE_CURRENT_SOURCE_DIR}"
119-
"${CMAKE_CURRENT_BINARY_DIR}/Source"
120-
DEPENDS flang-doc)
110+
# Generate the RST file from TableGen (shared by both HTML and MAN builds)
111+
gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs FlangOptionsDocs.td)
121112

122-
# Runs a python script prior to HTML generation to prepend a header to FIRLangRef,
123-
# Without the header, the page is incorrectly formatted, as it assumes the first entry is the page title.
124-
add_custom_command(TARGET copy-flang-src-docs
113+
if (${SPHINX_OUTPUT_HTML})
114+
message(STATUS "Using index.md for html build")
115+
116+
# Copy the entire flang/docs directory to the build Source dir,
117+
# then remove the index.rst file, to avoid clash with index.md
118+
# which is used for the HTML build.
119+
add_custom_target(copy-flang-src-docs-html
120+
COMMAND "${CMAKE_COMMAND}" -E copy_directory
121+
"${CMAKE_CURRENT_SOURCE_DIR}"
122+
"${FLANG_DOCS_HTML_DIR}"
123+
COMMAND "${CMAKE_COMMAND}" -E remove
124+
"${FLANG_DOCS_HTML_DIR}/CommandGuide/index.rst"
125+
COMMAND "${CMAKE_COMMAND}" -E copy
126+
"${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineReference.rst"
127+
"${FLANG_DOCS_HTML_DIR}/FlangCommandLineReference.rst"
128+
DEPENDS flang-doc gen-FlangCommandLineReference.rst)
129+
130+
# Run Python preprocessing ONLY for HTML build
131+
# This script prepends headers to FIRLangRef.md for proper formatting
132+
add_custom_command(TARGET copy-flang-src-docs-html
125133
COMMAND "${Python3_EXECUTABLE}"
126-
ARGS ${CMAKE_CURRENT_BINARY_DIR}/Source/FIR/CreateFIRLangRef.py)
134+
ARGS "${FLANG_DOCS_HTML_DIR}/FIR/CreateFIRLangRef.py")
127135

128-
# CLANG_TABLEGEN_EXE variable needs to be set for clang_tablegen to run without error
129-
find_program(CLANG_TABLEGEN_EXE "clang-tblgen" ${LLVM_TOOLS_BINARY_DIR} NO_DEFAULT_PATH)
130-
gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs FlangOptionsDocs.td docs-flang-html)
136+
add_sphinx_target(html flang SOURCE_DIR "${FLANG_DOCS_HTML_DIR}")
137+
add_dependencies(docs-flang-html copy-flang-src-docs-html)
131138
endif()
139+
140+
# ----------------------------
141+
# MAN BUILD SETUP
142+
# ----------------------------
132143
if (${SPHINX_OUTPUT_MAN})
133-
add_sphinx_target(man flang)
144+
message(STATUS "NOTE: The Flang man page is currently a placeholder with a TODO. See docs/CommandGuide/index.rst for details")
145+
146+
# Create minimal Source dir with ONLY the files needed for man build:
147+
# - conf.py (Sphinx config)
148+
# - index.rst (top-level man page)
149+
# - FlangCommandLineReference.rst (generated reference)
150+
add_custom_target(copy-flang-src-docs-man
151+
COMMAND "${CMAKE_COMMAND}" -E make_directory
152+
"${FLANG_DOCS_MAN_DIR}"
153+
COMMAND "${CMAKE_COMMAND}" -E copy
154+
"${CMAKE_CURRENT_SOURCE_DIR}/conf.py"
155+
"${FLANG_DOCS_MAN_DIR}/conf.py"
156+
COMMAND "${CMAKE_COMMAND}" -E copy
157+
"${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineReference.rst"
158+
"${FLANG_DOCS_MAN_DIR}/FlangCommandLineReference.rst"
159+
COMMAND "${CMAKE_COMMAND}" -E copy
160+
"${CMAKE_CURRENT_SOURCE_DIR}/CommandGuide/index.rst"
161+
"${FLANG_DOCS_MAN_DIR}/index.rst"
162+
DEPENDS flang-doc gen-FlangCommandLineReference.rst)
163+
164+
add_sphinx_target(man flang SOURCE_DIR "${FLANG_DOCS_MAN_DIR}")
165+
add_dependencies(docs-flang-man copy-flang-src-docs-man)
134166
endif()
135167
endif()
136168
endif()

‎flang/docs/CommandGuide/index.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
Flang Manual Page (In Progress)
2+
==================================================
3+
4+
.. note::
5+
This man page is under development.
6+
7+
For full documentation, please see the online HTML docs:
8+
9+
https://flang.llvm.org/docs/
10+
11+
..
12+
The placeholder text "FlangCommandLineReference" below should eventually be replaced with the actual man page contents.
13+
14+
----
15+
16+
Flang Command Line Reference
17+
----------------------------
18+
19+
.. toctree::
20+
:maxdepth: 1
21+
22+
FlangCommandLineReference

‎flang/docs/FIR/CreateFIRLangRef.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@
44
import os
55

66
# These paths are relative to flang/docs in the build directory, not source, as that's where this tool is executed.
7-
HEADER_PATH = os.path.join("Source", "FIR", "FIRLangRef_Header.md")
7+
HEADER_PATH = os.path.join("SourceHtml", "FIR", "FIRLangRef_Header.md")
88
DOCS_PATH = os.path.join("Dialect", "FIRLangRef.md")
9-
OUTPUT_PATH = os.path.join("Source", "FIRLangRef.md")
9+
OUTPUT_PATH = os.path.join("SourceHtml", "FIRLangRef.md")
1010

1111
# 1. Writes line 1 from docs to output, (comment line that the file is autogenerated)
1212
# 2. Adds a new line

‎flang/docs/conf.py

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -28,20 +28,22 @@
2828
"sphinx.ext.autodoc",
2929
]
3030

31-
# When building man pages, we do not use the markdown pages,
32-
# So, we can continue without the myst_parser dependencies.
33-
# Doing so reduces dependencies of some packaged llvm distributions.
3431
try:
3532
import myst_parser
3633

3734
extensions.append("myst_parser")
3835
except ImportError:
39-
if not tags.has("builder-man"):
40-
raise
36+
raise ImportError(
37+
"myst_parser is required to build documentation, including man pages."
38+
)
4139

4240

4341
# Add any paths that contain templates here, relative to this directory.
4442
templates_path = ["_templates"]
43+
source_suffix = {
44+
".rst": "restructuredtext",
45+
".md": "markdown",
46+
}
4547
myst_heading_anchors = 6
4648

4749
import sphinx
@@ -227,7 +229,15 @@
227229

228230
# One entry per manual page. List of tuples
229231
# (source start file, name, description, authors, manual section).
230-
man_pages = []
232+
man_pages = [
233+
(
234+
"index",
235+
"flang",
236+
"Flang Documentation (In Progress)",
237+
["Flang Contributors"],
238+
1,
239+
)
240+
]
231241

232242
# If true, show URL addresses after external links.
233243
# man_show_urls = False

0 commit comments

Comments
 (0)