Skip to content

[Flang] Add Sphinx man page and html support for Flang #141882

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 18 commits into from
Jun 4, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 57 additions & 25 deletions flang/docs/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -82,55 +82,87 @@ 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()
get_filename_component(TABLEGEN_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${source}" DIRECTORY)
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
# 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
)
add_dependencies("gen-${output_file}" create-flang-rst-output-dir)
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)
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)
# 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)

# 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)
# 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)

# 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
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}"
"${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
# 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")

# 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)
add_sphinx_target(html flang SOURCE_DIR "${FLANG_DOCS_HTML_DIR}")
add_dependencies(docs-flang-html copy-flang-src-docs-html)
endif()

# ----------------------------
# MAN BUILD SETUP
# ----------------------------
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man flang)
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)
# - index.rst (top-level man page)
# - FlangCommandLineReference.rst (generated reference)
add_custom_target(copy-flang-src-docs-man
COMMAND "${CMAKE_COMMAND}" -E make_directory
"${FLANG_DOCS_MAN_DIR}"
COMMAND "${CMAKE_COMMAND}" -E copy
"${CMAKE_CURRENT_SOURCE_DIR}/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"
"${FLANG_DOCS_MAN_DIR}/index.rst"
DEPENDS flang-doc gen-FlangCommandLineReference.rst)

add_sphinx_target(man flang SOURCE_DIR "${FLANG_DOCS_MAN_DIR}")
add_dependencies(docs-flang-man copy-flang-src-docs-man)
endif()
endif()
endif()
Expand Down
22 changes: 22 additions & 0 deletions flang/docs/CommandGuide/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
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/

..
The placeholder text "FlangCommandLineReference" below should eventually be replaced with the actual man page contents.
----

Flang Command Line Reference
----------------------------

.. toctree::
:maxdepth: 1

FlangCommandLineReference
4 changes: 2 additions & 2 deletions flang/docs/FIR/CreateFIRLangRef.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 16 additions & 6 deletions flang/docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,20 +28,22 @@
"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.
templates_path = ["_templates"]
source_suffix = {
".rst": "restructuredtext",
".md": "markdown",
}
myst_heading_anchors = 6

import sphinx
Expand Down Expand Up @@ -227,7 +229,15 @@

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = []
man_pages = [
(
"index",
"flang",
"Flang Documentation (In Progress)",
["Flang Contributors"],
1,
)
]

# If true, show URL addresses after external links.
# man_show_urls = False
Expand Down
Loading