mlir/tools/mlir-tblgen/PassDocGen.cpp

   1 //===- PassDocGen.cpp - MLIR pass documentation generator -----------------===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 // PassDocGen uses the description of passes to generate documentation.
  10 //
  11 //===----------------------------------------------------------------------===//
  12
  13 #include "DocGenUtilities.h"
  14 #include "mlir/TableGen/GenInfo.h"
  15 #include "mlir/TableGen/Pass.h"
  16 #include "llvm/Support/FormatVariadic.h"
  17 #include "llvm/TableGen/Record.h"
  18
  19 using namespace mlir;
  20 using namespace mlir::tblgen;
  21 using llvm::RecordKeeper;
  22
  23 /// Emit the documentation for the given pass.
  24 static void emitDoc(const Pass &pass, raw_ostream &os) {
  25   os << llvm::formatv("### `-{0}`\n", pass.getArgument());
  26   emitSummary(pass.getSummary(), os);
  27   emitDescription(pass.getDescription(), os);
  28
  29   // Handle the options of the pass.
  30   ArrayRef<PassOption> options = pass.getOptions();
  31   if (!options.empty()) {
  32     os << "\n#### Options\n```\n";
  33     size_t longestOption = 0;
  34     for (const PassOption &option : options)
  35       longestOption = std::max(option.getArgument().size(), longestOption);
  36     for (const PassOption &option : options) {
  37       os << "-" << option.getArgument();
  38       os.indent(longestOption - option.getArgument().size())
  39           << " : " << option.getDescription() << "\n";
  40     }
  41     os << "```\n";
  42   }
  43
  44   // Handle the statistics of the pass.
  45   ArrayRef<PassStatistic> stats = pass.getStatistics();
  46   if (!stats.empty()) {
  47     os << "\n#### Statistics\n```\n";
  48     size_t longestStat = 0;
  49     for (const PassStatistic &stat : stats)
  50       longestStat = std::max(stat.getName().size(), longestStat);
  51     for (const PassStatistic &stat : stats) {
  52       os << stat.getName();
  53       os.indent(longestStat - stat.getName().size())
  54           << " : " << stat.getDescription() << "\n";
  55     }
  56     os << "```\n";
  57   }
  58 }
  59
  60 static void emitDocs(const RecordKeeper &records, raw_ostream &os) {
  61   os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
  62   auto passDefs = records.getAllDerivedDefinitions("PassBase");
  63
  64   // Collect the registered passes, sorted by argument name.
  65   SmallVector<Pass, 16> passes(passDefs.begin(), passDefs.end());
  66   SmallVector<Pass *, 16> sortedPasses(llvm::make_pointer_range(passes));
  67   llvm::array_pod_sort(sortedPasses.begin(), sortedPasses.end(),
  68                        [](Pass *const *lhs, Pass *const *rhs) {
  69                          return (*lhs)->getArgument().compare(
  70                              (*rhs)->getArgument());
  71                        });
  72   for (Pass *pass : sortedPasses)
  73     emitDoc(*pass, os);
  74 }
  75
  76 static mlir::GenRegistration
  77     genRegister("gen-pass-doc", "Generate pass documentation",
  78                 [](const RecordKeeper &records, raw_ostream &os) {
  79                   emitDocs(records, os);
  80                   return false;
  81                 });