llvm-project

1
//===-- MDGenerator.cpp - Markdown Generator --------------------*- C++ -*-===//
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
#include "Generators.h"
10
#include "Representation.h"
11
#include "llvm/ADT/StringRef.h"
12
#include "llvm/Support/FileSystem.h"
13
#include "llvm/Support/Path.h"
14
#include <string>
15

16
using namespace llvm;
17

18
namespace clang {
19
namespace doc {
20

21
// Markdown generation
22

23
static std::string genItalic(const Twine &Text) {
24
  return "*" + Text.str() + "*";
25
}
26

27
static std::string genEmphasis(const Twine &Text) {
28
  return "**" + Text.str() + "**";
29
}
30

31
static std::string
32
genReferenceList(const llvm::SmallVectorImpl<Reference> &Refs) {
33
  std::string Buffer;
34
  llvm::raw_string_ostream Stream(Buffer);
35
  for (const auto &R : Refs) {
36
    if (&R != Refs.begin())
37
      Stream << ", ";
38
    Stream << R.Name;
39
  }
40
  return Stream.str();
41
}
42

43
static void writeLine(const Twine &Text, raw_ostream &OS) {
44
  OS << Text << "\n\n";
45
}
46

47
static void writeNewLine(raw_ostream &OS) { OS << "\n\n"; }
48

49
static void writeHeader(const Twine &Text, unsigned int Num, raw_ostream &OS) {
50
  OS << std::string(Num, '#') + " " + Text << "\n\n";
51
}
52

53
static void writeFileDefinition(const ClangDocContext &CDCtx, const Location &L,
54
                                raw_ostream &OS) {
55

56
  if (!CDCtx.RepositoryUrl) {
57
    OS << "*Defined at " << L.Filename << "#" << std::to_string(L.LineNumber)
58
       << "*";
59
  } else {
60
    OS << "*Defined at [" << L.Filename << "#" << std::to_string(L.LineNumber)
61
       << "](" << StringRef{*CDCtx.RepositoryUrl}
62
       << llvm::sys::path::relative_path(L.Filename) << "#"
63
       << std::to_string(L.LineNumber) << ")"
64
       << "*";
65
  }
66
  OS << "\n\n";
67
}
68

69
static void writeDescription(const CommentInfo &I, raw_ostream &OS) {
70
  if (I.Kind == "FullComment") {
71
    for (const auto &Child : I.Children)
72
      writeDescription(*Child, OS);
73
  } else if (I.Kind == "ParagraphComment") {
74
    for (const auto &Child : I.Children)
75
      writeDescription(*Child, OS);
76
    writeNewLine(OS);
77
  } else if (I.Kind == "BlockCommandComment") {
78
    OS << genEmphasis(I.Name);
79
    for (const auto &Child : I.Children)
80
      writeDescription(*Child, OS);
81
  } else if (I.Kind == "InlineCommandComment") {
82
    OS << genEmphasis(I.Name) << " " << I.Text;
83
  } else if (I.Kind == "ParamCommandComment") {
84
    std::string Direction = I.Explicit ? (" " + I.Direction).str() : "";
85
    OS << genEmphasis(I.ParamName) << I.Text << Direction;
86
    for (const auto &Child : I.Children)
87
      writeDescription(*Child, OS);
88
  } else if (I.Kind == "TParamCommandComment") {
89
    std::string Direction = I.Explicit ? (" " + I.Direction).str() : "";
90
    OS << genEmphasis(I.ParamName) << I.Text << Direction;
91
    for (const auto &Child : I.Children)
92
      writeDescription(*Child, OS);
93
  } else if (I.Kind == "VerbatimBlockComment") {
94
    for (const auto &Child : I.Children)
95
      writeDescription(*Child, OS);
96
  } else if (I.Kind == "VerbatimBlockLineComment") {
97
    OS << I.Text;
98
    writeNewLine(OS);
99
  } else if (I.Kind == "VerbatimLineComment") {
100
    OS << I.Text;
101
    writeNewLine(OS);
102
  } else if (I.Kind == "HTMLStartTagComment") {
103
    if (I.AttrKeys.size() != I.AttrValues.size())
104
      return;
105
    std::string Buffer;
106
    llvm::raw_string_ostream Attrs(Buffer);
107
    for (unsigned Idx = 0; Idx < I.AttrKeys.size(); ++Idx)
108
      Attrs << " \"" << I.AttrKeys[Idx] << "=" << I.AttrValues[Idx] << "\"";
109

110
    std::string CloseTag = I.SelfClosing ? "/>" : ">";
111
    writeLine("<" + I.Name + Attrs.str() + CloseTag, OS);
112
  } else if (I.Kind == "HTMLEndTagComment") {
113
    writeLine("</" + I.Name + ">", OS);
114
  } else if (I.Kind == "TextComment") {
115
    OS << I.Text;
116
  } else {
117
    OS << "Unknown comment kind: " << I.Kind << ".\n\n";
118
  }
119
}
120

121
static void writeNameLink(const StringRef &CurrentPath, const Reference &R,
122
                          llvm::raw_ostream &OS) {
123
  llvm::SmallString<64> Path = R.getRelativeFilePath(CurrentPath);
124
  // Paths in Markdown use POSIX separators.
125
  llvm::sys::path::native(Path, llvm::sys::path::Style::posix);
126
  llvm::sys::path::append(Path, llvm::sys::path::Style::posix,
127
                          R.getFileBaseName() + ".md");
128
  OS << "[" << R.Name << "](" << Path << ")";
129
}
130

131
static void genMarkdown(const ClangDocContext &CDCtx, const EnumInfo &I,
132
                        llvm::raw_ostream &OS) {
133
  if (I.Scoped)
134
    writeLine("| enum class " + I.Name + " |", OS);
135
  else
136
    writeLine("| enum " + I.Name + " |", OS);
137
  writeLine("--", OS);
138

139
  std::string Buffer;
140
  llvm::raw_string_ostream Members(Buffer);
141
  if (!I.Members.empty())
142
    for (const auto &N : I.Members)
143
      Members << "| " << N.Name << " |\n";
144
  writeLine(Members.str(), OS);
145
  if (I.DefLoc)
146
    writeFileDefinition(CDCtx, *I.DefLoc, OS);
147

148
  for (const auto &C : I.Description)
149
    writeDescription(C, OS);
150
}
151

152
static void genMarkdown(const ClangDocContext &CDCtx, const FunctionInfo &I,
153
                        llvm::raw_ostream &OS) {
154
  std::string Buffer;
155
  llvm::raw_string_ostream Stream(Buffer);
156
  bool First = true;
157
  for (const auto &N : I.Params) {
158
    if (!First)
159
      Stream << ", ";
160
    Stream << N.Type.Name + " " + N.Name;
161
    First = false;
162
  }
163
  writeHeader(I.Name, 3, OS);
164
  std::string Access = getAccessSpelling(I.Access).str();
165
  if (Access != "")
166
    writeLine(genItalic(Access + " " + I.ReturnType.Type.Name + " " + I.Name +
167
                        "(" + Stream.str() + ")"),
168
              OS);
169
  else
170
    writeLine(genItalic(I.ReturnType.Type.Name + " " + I.Name + "(" +
171
                        Stream.str() + ")"),
172
              OS);
173
  if (I.DefLoc)
174
    writeFileDefinition(CDCtx, *I.DefLoc, OS);
175

176
  for (const auto &C : I.Description)
177
    writeDescription(C, OS);
178
}
179

180
static void genMarkdown(const ClangDocContext &CDCtx, const NamespaceInfo &I,
181
                        llvm::raw_ostream &OS) {
182
  if (I.Name == "")
183
    writeHeader("Global Namespace", 1, OS);
184
  else
185
    writeHeader("namespace " + I.Name, 1, OS);
186
  writeNewLine(OS);
187

188
  if (!I.Description.empty()) {
189
    for (const auto &C : I.Description)
190
      writeDescription(C, OS);
191
    writeNewLine(OS);
192
  }
193

194
  llvm::SmallString<64> BasePath = I.getRelativeFilePath("");
195

196
  if (!I.Children.Namespaces.empty()) {
197
    writeHeader("Namespaces", 2, OS);
198
    for (const auto &R : I.Children.Namespaces) {
199
      OS << "* ";
200
      writeNameLink(BasePath, R, OS);
201
      OS << "\n";
202
    }
203
    writeNewLine(OS);
204
  }
205

206
  if (!I.Children.Records.empty()) {
207
    writeHeader("Records", 2, OS);
208
    for (const auto &R : I.Children.Records) {
209
      OS << "* ";
210
      writeNameLink(BasePath, R, OS);
211
      OS << "\n";
212
    }
213
    writeNewLine(OS);
214
  }
215

216
  if (!I.Children.Functions.empty()) {
217
    writeHeader("Functions", 2, OS);
218
    for (const auto &F : I.Children.Functions)
219
      genMarkdown(CDCtx, F, OS);
220
    writeNewLine(OS);
221
  }
222
  if (!I.Children.Enums.empty()) {
223
    writeHeader("Enums", 2, OS);
224
    for (const auto &E : I.Children.Enums)
225
      genMarkdown(CDCtx, E, OS);
226
    writeNewLine(OS);
227
  }
228
}
229

230
static void genMarkdown(const ClangDocContext &CDCtx, const RecordInfo &I,
231
                        llvm::raw_ostream &OS) {
232
  writeHeader(getTagType(I.TagType) + " " + I.Name, 1, OS);
233
  if (I.DefLoc)
234
    writeFileDefinition(CDCtx, *I.DefLoc, OS);
235

236
  if (!I.Description.empty()) {
237
    for (const auto &C : I.Description)
238
      writeDescription(C, OS);
239
    writeNewLine(OS);
240
  }
241

242
  std::string Parents = genReferenceList(I.Parents);
243
  std::string VParents = genReferenceList(I.VirtualParents);
244
  if (!Parents.empty() || !VParents.empty()) {
245
    if (Parents.empty())
246
      writeLine("Inherits from " + VParents, OS);
247
    else if (VParents.empty())
248
      writeLine("Inherits from " + Parents, OS);
249
    else
250
      writeLine("Inherits from " + Parents + ", " + VParents, OS);
251
    writeNewLine(OS);
252
  }
253

254
  if (!I.Members.empty()) {
255
    writeHeader("Members", 2, OS);
256
    for (const auto &Member : I.Members) {
257
      std::string Access = getAccessSpelling(Member.Access).str();
258
      if (Access != "")
259
        writeLine(Access + " " + Member.Type.Name + " " + Member.Name, OS);
260
      else
261
        writeLine(Member.Type.Name + " " + Member.Name, OS);
262
    }
263
    writeNewLine(OS);
264
  }
265

266
  if (!I.Children.Records.empty()) {
267
    writeHeader("Records", 2, OS);
268
    for (const auto &R : I.Children.Records)
269
      writeLine(R.Name, OS);
270
    writeNewLine(OS);
271
  }
272
  if (!I.Children.Functions.empty()) {
273
    writeHeader("Functions", 2, OS);
274
    for (const auto &F : I.Children.Functions)
275
      genMarkdown(CDCtx, F, OS);
276
    writeNewLine(OS);
277
  }
278
  if (!I.Children.Enums.empty()) {
279
    writeHeader("Enums", 2, OS);
280
    for (const auto &E : I.Children.Enums)
281
      genMarkdown(CDCtx, E, OS);
282
    writeNewLine(OS);
283
  }
284
}
285

286
static void genMarkdown(const ClangDocContext &CDCtx, const TypedefInfo &I,
287
                        llvm::raw_ostream &OS) {
288
  // TODO support typedefs in markdown.
289
}
290

291
static void serializeReference(llvm::raw_fd_ostream &OS, Index &I, int Level) {
292
  // Write out the heading level starting at ##
293
  OS << "##" << std::string(Level, '#') << " ";
294
  writeNameLink("", I, OS);
295
  OS << "\n";
296
}
297

298
static llvm::Error serializeIndex(ClangDocContext &CDCtx) {
299
  std::error_code FileErr;
300
  llvm::SmallString<128> FilePath;
301
  llvm::sys::path::native(CDCtx.OutDirectory, FilePath);
302
  llvm::sys::path::append(FilePath, "all_files.md");
303
  llvm::raw_fd_ostream OS(FilePath, FileErr, llvm::sys::fs::OF_None);
304
  if (FileErr)
305
    return llvm::createStringError(llvm::inconvertibleErrorCode(),
306
                                   "error creating index file: " +
307
                                       FileErr.message());
308

309
  CDCtx.Idx.sort();
310
  OS << "# All Files";
311
  if (!CDCtx.ProjectName.empty())
312
    OS << " for " << CDCtx.ProjectName;
313
  OS << "\n\n";
314

315
  for (auto C : CDCtx.Idx.Children)
316
    serializeReference(OS, C, 0);
317

318
  return llvm::Error::success();
319
}
320

321
static llvm::Error genIndex(ClangDocContext &CDCtx) {
322
  std::error_code FileErr;
323
  llvm::SmallString<128> FilePath;
324
  llvm::sys::path::native(CDCtx.OutDirectory, FilePath);
325
  llvm::sys::path::append(FilePath, "index.md");
326
  llvm::raw_fd_ostream OS(FilePath, FileErr, llvm::sys::fs::OF_None);
327
  if (FileErr)
328
    return llvm::createStringError(llvm::inconvertibleErrorCode(),
329
                                   "error creating index file: " +
330
                                       FileErr.message());
331
  CDCtx.Idx.sort();
332
  OS << "# " << CDCtx.ProjectName << " C/C++ Reference\n\n";
333
  for (auto C : CDCtx.Idx.Children) {
334
    if (!C.Children.empty()) {
335
      const char *Type;
336
      switch (C.RefType) {
337
      case InfoType::IT_namespace:
338
        Type = "Namespace";
339
        break;
340
      case InfoType::IT_record:
341
        Type = "Type";
342
        break;
343
      case InfoType::IT_enum:
344
        Type = "Enum";
345
        break;
346
      case InfoType::IT_function:
347
        Type = "Function";
348
        break;
349
      case InfoType::IT_typedef:
350
        Type = "Typedef";
351
        break;
352
      case InfoType::IT_default:
353
        Type = "Other";
354
      }
355
      OS << "* " << Type << ": [" << C.Name << "](";
356
      if (!C.Path.empty())
357
        OS << C.Path << "/";
358
      OS << C.Name << ")\n";
359
    }
360
  }
361
  return llvm::Error::success();
362
}
363

364
/// Generator for Markdown documentation.
365
class MDGenerator : public Generator {
366
public:
367
  static const char *Format;
368

369
  llvm::Error generateDocs(StringRef RootDir,
370
                           llvm::StringMap<std::unique_ptr<doc::Info>> Infos,
371
                           const ClangDocContext &CDCtx) override;
372
  llvm::Error createResources(ClangDocContext &CDCtx) override;
373
  llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS,
374
                                 const ClangDocContext &CDCtx) override;
375
};
376

377
const char *MDGenerator::Format = "md";
378

379
llvm::Error
380
MDGenerator::generateDocs(StringRef RootDir,
381
                          llvm::StringMap<std::unique_ptr<doc::Info>> Infos,
382
                          const ClangDocContext &CDCtx) {
383
  // Track which directories we already tried to create.
384
  llvm::StringSet<> CreatedDirs;
385

386
  // Collect all output by file name and create the necessary directories.
387
  llvm::StringMap<std::vector<doc::Info *>> FileToInfos;
388
  for (const auto &Group : Infos) {
389
    doc::Info *Info = Group.getValue().get();
390

391
    llvm::SmallString<128> Path;
392
    llvm::sys::path::native(RootDir, Path);
393
    llvm::sys::path::append(Path, Info->getRelativeFilePath(""));
394
    if (!CreatedDirs.contains(Path)) {
395
      if (std::error_code Err = llvm::sys::fs::create_directories(Path);
396
          Err != std::error_code()) {
397
        return llvm::createStringError(Err, "Failed to create directory '%s'.",
398
                                       Path.c_str());
399
      }
400
      CreatedDirs.insert(Path);
401
    }
402

403
    llvm::sys::path::append(Path, Info->getFileBaseName() + ".md");
404
    FileToInfos[Path].push_back(Info);
405
  }
406

407
  for (const auto &Group : FileToInfos) {
408
    std::error_code FileErr;
409
    llvm::raw_fd_ostream InfoOS(Group.getKey(), FileErr,
410
                                llvm::sys::fs::OF_None);
411
    if (FileErr) {
412
      return llvm::createStringError(FileErr, "Error opening file '%s'",
413
                                     Group.getKey().str().c_str());
414
    }
415

416
    for (const auto &Info : Group.getValue()) {
417
      if (llvm::Error Err = generateDocForInfo(Info, InfoOS, CDCtx)) {
418
        return Err;
419
      }
420
    }
421
  }
422

423
  return llvm::Error::success();
424
}
425

426
llvm::Error MDGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS,
427
                                            const ClangDocContext &CDCtx) {
428
  switch (I->IT) {
429
  case InfoType::IT_namespace:
430
    genMarkdown(CDCtx, *static_cast<clang::doc::NamespaceInfo *>(I), OS);
431
    break;
432
  case InfoType::IT_record:
433
    genMarkdown(CDCtx, *static_cast<clang::doc::RecordInfo *>(I), OS);
434
    break;
435
  case InfoType::IT_enum:
436
    genMarkdown(CDCtx, *static_cast<clang::doc::EnumInfo *>(I), OS);
437
    break;
438
  case InfoType::IT_function:
439
    genMarkdown(CDCtx, *static_cast<clang::doc::FunctionInfo *>(I), OS);
440
    break;
441
  case InfoType::IT_typedef:
442
    genMarkdown(CDCtx, *static_cast<clang::doc::TypedefInfo *>(I), OS);
443
    break;
444
  case InfoType::IT_default:
445
    return createStringError(llvm::inconvertibleErrorCode(),
446
                             "unexpected InfoType");
447
  }
448
  return llvm::Error::success();
449
}
450

451
llvm::Error MDGenerator::createResources(ClangDocContext &CDCtx) {
452
  // Write an all_files.md
453
  auto Err = serializeIndex(CDCtx);
454
  if (Err)
455
    return Err;
456

457
  // Generate the index page.
458
  Err = genIndex(CDCtx);
459
  if (Err)
460
    return Err;
461

462
  return llvm::Error::success();
463
}
464

465
static GeneratorRegistry::Add<MDGenerator> MD(MDGenerator::Format,
466
                                              "Generator for MD output.");
467

468
// This anchor is used to force the linker to link in the generated object
469
// file and thus register the generator.
470
volatile int MDGeneratorAnchorSource = 0;
471

472
} // namespace doc
473
} // namespace clang
474