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
  22 /// Emit the documentation for the given pass.
  23 static void emitDoc(const Pass &pass, raw_ostream &os) {
  24   os << llvm::formatv("### `-{0}`\n", pass.getArgument());
  25   emitSummary(pass.getSummary(), os);
  26   emitDescription(pass.getDescription(), os);
  27
  28   // Handle the options of the pass.
  29   ArrayRef<PassOption> options = pass.getOptions();
  30   if (!options.empty()) {
  31     os << "\n#### Options\n```\n";
  32     size_t longestOption = 0;
  33     for (const PassOption &option : options)
  34       longestOption = std::max(option.getArgument().size(), longestOption);
  35     for (const PassOption &option : options) {
  36       os << "-" << option.getArgument();
  37       os.indent(longestOption - option.getArgument().size())
  38           << " : " << option.getDescription() << "\n";
  39     }
  40     os << "```\n";
  41   }
  42
  43   // Handle the statistics of the pass.
  44   ArrayRef<PassStatistic> stats = pass.getStatistics();
  45   if (!stats.empty()) {
  46     os << "\n#### Statistics\n```\n";
  47     size_t longestStat = 0;
  48     for (const PassStatistic &stat : stats)
  49       longestStat = std::max(stat.getName().size(), longestStat);
  50     for (const PassStatistic &stat : stats) {
  51       os << stat.getName();
  52       os.indent(longestStat - stat.getName().size())
  53           << " : " << stat.getDescription() << "\n";
  54     }
  55     os << "```\n";
  56   }
  57 }
  58
  59 static void emitDocs(const llvm::RecordKeeper &recordKeeper, raw_ostream &os) {
  60   os << "<!-- Autogenerated by mlir-tblgen; don't manually edit -->\n";
  61   auto passDefs = recordKeeper.getAllDerivedDefinitions("PassBase");
  62
  63   // Collect the registered passes, sorted by argument name.
  64   SmallVector<Pass, 16> passes(passDefs.begin(), passDefs.end());
  65   SmallVector<Pass *, 16> sortedPasses(llvm::make_pointer_range(passes));
  66   llvm::array_pod_sort(sortedPasses.begin(), sortedPasses.end(),
  67                        [](Pass *const *lhs, Pass *const *rhs) {
  68                          return (*lhs)->getArgument().compare(
  69                              (*rhs)->getArgument());
  70                        });
  71   for (Pass *pass : sortedPasses)
  72     emitDoc(*pass, os);
  73 }
  74
  75 static mlir::GenRegistration
  76     genRegister("gen-pass-doc", "Generate pass documentation",
  77                 [](const llvm::RecordKeeper &records, raw_ostream &os) {
  78                   emitDocs(records, os);
  79                   return false;
  80                 });