[flang-commits] [flang] 396e944 - [Flang] Generate documentation for compiler flags

[Dylan Fleming via flang-commits]

Author: Dylan Fleming
Date: 2022-07-21T11:33:19Z
New Revision: 396e944d82f3e212746cd241e4caba445523aff6

URL: https://github.com/llvm/llvm-project/commit/396e944d82f3e212746cd241e4caba445523aff6
DIFF: https://github.com/llvm/llvm-project/commit/396e944d82f3e212746cd241e4caba445523aff6.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.

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..077c01d3310ff 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)
@@ -114,6 +124,7 @@ if (LLVM_ENABLE_SPHINX)
           COMMAND "${Python3_EXECUTABLE}"
           ARGS ${CMAKE_CURRENT_BINARY_DIR}/Source/FIR/CreateFIRLangRef.py)
 
+      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"