[clang] 846439d - [Flang] Generate documentation for compiler flags
Dylan Fleming via cfe-commits
cfe-commits at lists.llvm.org
Fri Jul 22 10:05:34 PDT 2022
Author: Dylan Fleming
Date: 2022-07-22T17:05:04Z
New Revision: 846439dd97d45e0e08af14269708511646a9add1
URL: https://github.com/llvm/llvm-project/commit/846439dd97d45e0e08af14269708511646a9add1
DIFF: https://github.com/llvm/llvm-project/commit/846439dd97d45e0e08af14269708511646a9add1.diff
LOG: [Flang] Generate documentation for compiler flags
This patch aims to create a webpage to document
Flang's command line options on https://flang.llvm.org/docs/
in a similar way to Clang's
https://clang.llvm.org/docs/ClangCommandLineReference.html
This is done by using clang_tablegen to generate an .rst
file from Options.td (which is current shared with Clang)
For this to work, ClangOptionDocEmitter.cpp was updated
to allow specific Flang flags to be included,
rather than bulk excluding clang flags.
Note:
Some headings in the generated documentation will incorrectly
contain references to Clang, e.g.
"Flags controlling the behaviour of Clang during compilation"
This is because Options.td (Which is shared between both Clang and Flang)
contains hard-coded DocBrief sections. I couldn't find a non-intrusive way
to make this target-dependant, as such I've left this as is, and it will need revisiting later.
Reviewed By: awarzynski
Differential Revision: https://reviews.llvm.org/D129864
Added:
flang/include/flang/FlangOptionsDocs.td
Modified:
clang/utils/TableGen/ClangOptionDocEmitter.cpp
flang/docs/CMakeLists.txt
flang/docs/index.md
Removed:
################################################################################
diff --git a/clang/utils/TableGen/ClangOptionDocEmitter.cpp b/clang/utils/TableGen/ClangOptionDocEmitter.cpp
index 6c24ad2bdcc53..75f5d057c33a5 100644
--- a/clang/utils/TableGen/ClangOptionDocEmitter.cpp
+++ b/clang/utils/TableGen/ClangOptionDocEmitter.cpp
@@ -168,6 +168,29 @@ bool hasFlag(const Record *OptionOrGroup, StringRef OptionFlag) {
return false;
}
+bool isIncluded(const Record *OptionOrGroup, const Record *DocInfo) {
+ assert(DocInfo->getValue("IncludedFlags") && "Missing includeFlags");
+ for (StringRef Inclusion : DocInfo->getValueAsListOfStrings("IncludedFlags"))
+ if (hasFlag(OptionOrGroup, Inclusion))
+ return true;
+ return false;
+}
+
+bool isGroupIncluded(const DocumentedGroup &Group, const Record *DocInfo) {
+ if (isIncluded(Group.Group, DocInfo))
+ return true;
+ for (auto &O : Group.Options)
+ if (isIncluded(O.Option, DocInfo))
+ return true;
+ for (auto &G : Group.Groups) {
+ if (isIncluded(G.Group, DocInfo))
+ return true;
+ if (isGroupIncluded(G, DocInfo))
+ return true;
+ }
+ return false;
+}
+
bool isExcluded(const Record *OptionOrGroup, const Record *DocInfo) {
// FIXME: Provide a flag to specify the set of exclusions.
for (StringRef Exclusion : DocInfo->getValueAsListOfStrings("ExcludedFlags"))
@@ -304,6 +327,8 @@ void emitOption(const DocumentedOption &Option, const Record *DocInfo,
raw_ostream &OS) {
if (isExcluded(Option.Option, DocInfo))
return;
+ if (DocInfo->getValue("IncludedFlags") && !isIncluded(Option.Option, DocInfo))
+ return;
if (Option.Option->getValueAsDef("Kind")->getName() == "KIND_UNKNOWN" ||
Option.Option->getValueAsDef("Kind")->getName() == "KIND_INPUT")
return;
@@ -379,6 +404,9 @@ void emitGroup(int Depth, const DocumentedGroup &Group, const Record *DocInfo,
if (isExcluded(Group.Group, DocInfo))
return;
+ if (DocInfo->getValue("IncludedFlags") && !isGroupIncluded(Group, DocInfo))
+ return;
+
emitHeading(Depth,
getRSTStringWithTextFallback(Group.Group, "DocName", "Name"), OS);
diff --git a/flang/docs/CMakeLists.txt b/flang/docs/CMakeLists.txt
index 044697a104507..b742be5e12f42 100644
--- a/flang/docs/CMakeLists.txt
+++ b/flang/docs/CMakeLists.txt
@@ -91,6 +91,16 @@ if (LLVM_ENABLE_DOXYGEN)
endif()
endif()
+function (gen_rst_file_from_td output_file td_option source docs_target)
+ 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}")
+ clang_tablegen(Source/${output_file} ${td_option} SOURCE ${source} TARGET "gen-${output_file}")
+ add_dependencies(${docs_target} "gen-${output_file}")
+endfunction()
+
if (LLVM_ENABLE_SPHINX)
include(AddSphinxTarget)
if (SPHINX_FOUND)
@@ -108,12 +118,15 @@ if (LLVM_ENABLE_SPHINX)
"${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)
+ # 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
+ set(CLANG_TABLEGEN_EXE clang-tblgen)
+ gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs ../include/flang/FlangOptionsDocs.td docs-flang-html)
endif()
if (${SPHINX_OUTPUT_MAN})
add_sphinx_target(man flang)
diff --git a/flang/docs/index.md b/flang/docs/index.md
index 3c3e2de2a8078..d6b05115f8611 100644
--- a/flang/docs/index.md
+++ b/flang/docs/index.md
@@ -45,6 +45,7 @@ on how to get in touch with us and to learn more about the current status.
DoConcurrent
Extensions
FIRLangRef
+ FlangCommandLineReference
FlangDriver
FortranIR
FortranLLVMTestSuite
diff --git a/flang/include/flang/FlangOptionsDocs.td b/flang/include/flang/FlangOptionsDocs.td
new file mode 100644
index 0000000000000..32054428ad3f8
--- /dev/null
+++ b/flang/include/flang/FlangOptionsDocs.td
@@ -0,0 +1,35 @@
+//==--- FlangOptionDocs.td - Option documentation -------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+def GlobalDocumentation {
+ code Intro =[{..
+ -------------------------------------------------------------------
+ NOTE: This file is automatically generated by running clang-tblgen
+ -gen-opt-docs. Do not edit this file by hand!!
+ -------------------------------------------------------------------
+
+=====================================
+Flang command line argument reference
+=====================================
+.. contents::
+ :local:
+
+Introduction
+============
+
+}];
+
+ string Program = "flang";
+
+ list<string> ExcludedFlags = [];
+ list<string> IncludedFlags = ["FlangOption"];
+
+}
+
+
+include "../../../clang/include/clang/Driver/Options.td"
More information about the cfe-commits
mailing list