[flang] flang manpage overhaul (llvm#144948)

Make the flang man page look more like the one clang is having.

Author: pawosm-arm

flang/docs/CMakeLists.txt

@@ -82,20 +82,14 @@ if (LLVM_ENABLE_DOXYGEN)
 endif()
 endif()
 
-function (gen_rst_file_from_td output_file td_option source)
+function (gen_rst_file_from_td output_file td_option source 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}")
   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}")
-  # clang_tablegen() does not create the output directory automatically,
-  # 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)
+  clang_tablegen(Source/${output_file} ${td_option} SOURCE ${source} TARGET ${target})
 endfunction()
 
 if (LLVM_ENABLE_SPHINX)
@@ -107,14 +101,22 @@ if (LLVM_ENABLE_SPHINX)
     # 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)
 
-    # 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)
+    # Generate the RST file from TableGen (for both HTML and MAN builds)
+    gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs FlangOptionsDocs.td "gen-FlangCommandLineReference.rst")
+    gen_rst_file_from_td(FlangCommandLineOptions.rst -gen-opt-docs FlangOptionsMan.td "gen-FlangCommandLineOptions.rst")
+    # clang_tablegen() (called from gen_rst_file_from_td()) does not create the
+    # output directory automatically, 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-FlangCommandLineReference.rst" create-flang-rst-output-dir)
+    add_dependencies("gen-FlangCommandLineOptions.rst" create-flang-rst-output-dir)
 
     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 
+      # 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
@@ -141,26 +143,26 @@ if (LLVM_ENABLE_SPHINX)
     # MAN BUILD SETUP
     # ----------------------------
     if (${SPHINX_OUTPUT_MAN})
-      message(STATUS "NOTE: The Flang man page is currently a placeholder with a TODO. See docs/CommandGuide/index.rst for details")
+      message(STATUS "Using CommandGuide/index.rst for man build")
 
       # 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)
+      # - FlangCommandLineOptions.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"
+          "${CMAKE_CURRENT_BINARY_DIR}/Source/FlangCommandLineOptions.rst"
+          "${FLANG_DOCS_MAN_DIR}/FlangCommandLineOptions.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)
-        
+        DEPENDS flang-doc gen-FlangCommandLineOptions.rst)
+
       add_sphinx_target(man flang SOURCE_DIR "${FLANG_DOCS_MAN_DIR}")
       add_dependencies(docs-flang-man copy-flang-src-docs-man)
     endif()

flang/docs/CommandGuide/index.rst

@@ -1,22 +1,63 @@
-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
-----------------------------
+flang - the Flang Fortran compiler
+==================================
+
+SYNOPSIS
+--------
+
+:program:`flang` [*options*] *filename ...*
+
+DESCRIPTION
+-----------
+
+:program:`flang` is a Fortran compiler which supports all of the Fortran 95 and
+many newer language features. Flang supports OpenMP and has some support for
+OpenACC and CUDA. It encompasses preprocessing, parsing, optimization, code
+generation, assembly, and linking.  Depending on the options passed in, Flang
+will perform only some, or all, of these actions. While Flang is highly
+integrated, it is important to understand the stages of compilation in order to
+understand how to invoke it.  These stages are:
+
+Driver
+    The flang executable is actually a small driver that orchestrates the
+    execution of other tools such as the compiler, assembler and linker.
+    Typically you do not need to interact with the driver, but you
+    transparently use it to run the other tools.
+
+Preprocessing
+    This stage performs tokenization of the input source file, macro expansion,
+    #include expansion and handles other preprocessor directives.
+
+Parsing and Semantic Analysis
+    This stage parses the input file, translating preprocessor tokens into a
+    parse tree.  Once in the form of a parse tree, it applies semantic
+    analysis to compute types for expressions and determine whether
+    the code is well formed. Parse errors and most compiler warnings
+    are generated by this stage.
+
+Code Generation and Optimization
+    This stage translates the parse tree into intermediate code (known as
+    "LLVM IR") and, ultimately, machine code.  It also optimizes this
+    intermediate code and handles target-specific code generation. The output
+    of this stage is typically a ".s" file, referred to as an "assembly" file.
+
+    Flang also supports the use of an integrated assembler, in which the code
+    generator produces object files directly. This avoids the overhead of
+    generating the ".s" file and calling the target assembler explicitly.
+
+Assembler
+    This stage runs the target assembler to translate the output of the
+    compiler into a target object file. The output of this stage is typically
+    a ".o" file, referred to as an "object" file.
+
+Linker
+    This stage runs the target linker to merge multiple object files into an
+    executable or dynamic library. The output of this stage is typically
+    an "a.out", ".dylib" or ".so" file.
+
+OPTIONS
+-------
 
 .. toctree::
    :maxdepth: 1
 
-   FlangCommandLineReference
+   FlangCommandLineOptions

flang/docs/FlangOptionsDocs.td

@@ -1,4 +1,4 @@
-//==--- FlangOptionDocs.td - Option documentation -------------------------===//
+//==--- FlangOptionsDocs.td - Options documentation -----------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.

flang/docs/FlangOptionsMan.td

@@ -0,0 +1,23 @@
+//==--- FlangOptionsMan.td - Options 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!!
+  -------------------------------------------------------------------
+}];
+
+  string Program = "Flang";
+  list<string> VisibilityMask = ["FlangOption"];
+  list<string> IgnoreFlags = ["HelpHidden", "Unsupported", "Ignored"];
+}
+
+#define GENERATING_DOCS
+include "Options.td"

flang/docs/conf.py

@@ -233,7 +233,7 @@
     (
         "index",
         "flang",
-        "Flang Documentation (In Progress)",
+        "flang - the Flang Fortran compiler",
         ["Flang Contributors"],
         1,
     )