[clang-doc] Improving Markdown Output

[Clayton]

Summary

This change has two components. The moves the generated file
 for a namespace to the directory named after the namespace in
 a file named 'index.<format>'. This greatly improves the browsing
 experience since the index page is shown by default for a directory.
 
 The second improves the markdown output by adding the links to the
 referenced pages for children objects and the link back to the source
 code.

[juliehockett]

Thanks so much for doing this! Would you be able to link some screenshots? Just so I can have a better sense of what's changing here.

clang-tools-extra/clang-doc/Representation.h

271

s/Reference/Info

[Clayton]

The output for for html did not change - what changed was the path for namespaces. For example the "async" namespace was in documented in async.html, and the types and functions in async where in async/*.html. After this change the "async" namespace is documented in async/index.html. This makes browsing very nice.

On the markdown side, I added the link functionality that existed on the HTML output for linking to classes and child namespaces.

Before	After

[Clayton]

Updated comment in Representation.h based on reviewer feedback.

[Clayton]

clang-tools-extra/clang-doc/Representation.h

271

Done.

[phosek]

clang-tools-extra/clang-doc/MDGenerator.cpp

282

level should be Level.

283

Nit: no extra empty line.

297

No need for OK, you can simply do if (FileErr).

301

No curly braces for blocks with a single statement according to LLVM style.

306

The same here, no curly braces for blocks with a single statement according to LLVM style.

311

Here as well.

322

The same here, both the error checking and curly braces.

clang-tools-extra/clang-doc/Representation.cpp

124

iter should be Iter (or just I) according to LLVM style.

134

No curly braces for blocks with a single statement.

146

No curly braces for blocks with a single statement.

159

No curly braces for blocks with a single statement.

[Clayton]

Updates to conform to LLVM style guide per reviewer feedback.

clang-tools-extra/clang-doc/MDGenerator.cpp

282

Done. Found https://llvm.org/docs/CodingStandards.html#name-types-functions-variables-and-enumerators-properly

[phosek]

LGTM % one minor nit, do you want me to land this for you?

clang-tools-extra/clang-doc/assets/index.js

33–34

You could omit braces here as well (we've been following C/C++ style guide for JS).

[Clayton]

Removed unnecessary braces in index.js

[Clayton]

Yes, please merge the change. Out of curiosity, is there a linter that can be used to help check for style rule adherence?

[thakis]

Looks like this breaks the build: http://45.33.8.238/linux/9048/step_4.txt

[Clayton]

Fixing build error

[Clayton]

build error fixed.

[Clayton]

Fixing unit tests affected by this change.

[Clayton]

Updating tests affected by this change.

[phosek]

This is failing on Windows:

../../clang-tools-extra/unittests/clang-doc/MDGeneratorTest.cpp(77): error:       Expected: Expected
      Which is: "# namespace Namespace\n\n\n\n## Namespaces\n\n* [ChildNamespace](../ChildNamespace/index.md)\n\n\n## Records\n\n* [ChildStruct](../ChildStruct.md)\n\n\n## Functions\n\n### OneFunction\n\n* OneFunction()*\n\n\n\n## Enums\n\n| enum OneEnum |\n\n--\n\n\n\n\n\n"
To be equal to: Actual.str()
      Which is: "# namespace Namespace\n\n\n\n## Namespaces\n\n* [ChildNamespace](..\\ChildNamespace\\index.md)\n\n\n## Records\n\n* [ChildStruct](..\\ChildStruct.md)\n\n\n## Functions\n\n### OneFunction\n\n* OneFunction()*\n\n\n\n## Enums\n\n| enum OneEnum |\n\n--\n\n\n\n\n\n"
With diff:
@@ -5,5 +5,5 @@
 ## Namespaces
 
-* [ChildNamespace](../ChildNamespace/index.md)
+* [ChildNamespace](..\\ChildNamespace\\index.md)
 
 
@@ -10,5 +10,5 @@
 ## Records
 
-* [ChildStruct](../ChildStruct.md)
+* [ChildStruct](..\\ChildStruct.md)
 
 

[  FAILED  ] MDGeneratorTest.emitNamespaceMD (1 ms)
[----------] 1 test from MDGeneratorTest (1 ms total)

[----------] Global test environment tear-down
[==========] 1 test from 1 test case ran. (1 ms total)
[  PASSED  ] 0 tests.
[  FAILED  ] 1 test, listed below:
[  FAILED  ] MDGeneratorTest.emitNamespaceMD

 1 FAILED TEST

[Clayton]

Re-opening to fix windows tests failures.

[Clayton]

Making paths in markdown files be posix style. This fixes the tests on windows hosts.

[phosek]

This is still failing on Windows:

******************** TEST 'Extra Tools Unit Tests :: clang-doc/./ClangDocTests.exe/MDGeneratorTest.emitNamespaceMD' FAILED ********************
Note: Google Test filter = MDGeneratorTest.emitNamespaceMD

[==========] Running 1 test from 1 test case.

[----------] Global test environment set-up.

[----------] 1 test from MDGeneratorTest

[ RUN      ] MDGeneratorTest.emitNamespaceMD

C:\ps4-buildslave2\llvm-clang-lld-x86_64-scei-ps4-windows10pro-fast\llvm-project\clang-tools-extra\unittests\clang-doc\MDGeneratorTest.cpp(77): error:       Expected: Expected

      Which is: "# namespace Namespace\n\n\n\n## Namespaces\n\n* [ChildNamespace](../ChildNamespace/index.md)\n\n\n## Records\n\n* [ChildStruct](../ChildStruct.md)\n\n\n## Functions\n\n### OneFunction\n\n* OneFunction()*\n\n\n\n## Enums\n\n| enum OneEnum |\n\n--\n\n\n\n\n\n"

To be equal to: Actual.str()

      Which is: "# namespace Namespace\n\n\n\n## Namespaces\n\n* [ChildNamespace](../ChildNamespace/index.md)\n\n\n## Records\n\n* [ChildStruct](..//ChildStruct.md)\n\n\n## Functions\n\n### OneFunction\n\n* OneFunction()*\n\n\n\n## Enums\n\n| enum OneEnum |\n\n--\n\n\n\n\n\n"

With diff:

@@ -10,5 +10,5 @@

 ## Records

 

-* [ChildStruct](../ChildStruct.md)

+* [ChildStruct](..//ChildStruct.md)

 

 



[  FAILED  ] MDGeneratorTest.emitNamespaceMD (1 ms)

[----------] 1 test from MDGeneratorTest (1 ms total)



[----------] Global test environment tear-down

[==========] 1 test from 1 test case ran. (1 ms total)

[  PASSED  ] 0 tests.

[  FAILED  ] 1 test, listed below:

[  FAILED  ] MDGeneratorTest.emitNamespaceMD



 1 FAILED TEST

clang-tools-extra/clang-doc/HTMLGenerator.cpp

 genReference(const Reference &Type, StringRef CurrentDirectory,
              llvm::Optional<StringRef> JumpToSection = None) {
   if (Type.Path.empty() && !Type.IsInGlobalNamespace) {
     if (!JumpToSection)
       return std::make_unique<TextNode>(Type.Name);
     else
       return genLink(Type.Name, "#" + JumpToSection.getValue());
   }
-  llvm::SmallString<128> Path =
-      computeRelativePath(Type.Path, CurrentDirectory);
-  llvm::sys::path::append(Path, Type.Name + ".html");
+  llvm::SmallString<64> Path = Type.getRelativeFilePath(CurrentDirectory);
+  llvm::sys::path::append(Path, Type.getFileBaseName() + ".html");
+
   // Paths in HTML must be in posix-style
   llvm::sys::path::native(Path, llvm::sys::path::Style::posix);
   if (JumpToSection)
     Path += ("#" + JumpToSection.getValue()).str();
   return genLink(Type.Name, Path);
 }
 
 static std::vector<std::unique_ptr<HTMLNode>>
else
     InfoTitle = ("namespace " + I.Name).str();
 
   Out.emplace_back(std::make_unique<TagNode>(HTMLTag::TAG_H1, InfoTitle));
 
   std::string Description;
   if (!I.Description.empty())
     Out.emplace_back(genHTML(I.Description));
 
+  llvm::SmallString<64> BasePath = I.getRelativeFilePath("");
+
   std::vector<std::unique_ptr<TagNode>> ChildNamespaces =
-      genReferencesBlock(I.ChildNamespaces, "Namespaces", I.Path);
+      genReferencesBlock(I.ChildNamespaces, "Namespaces", BasePath);
   AppendVector(std::move(ChildNamespaces), Out);
   std::vector<std::unique_ptr<TagNode>> ChildRecords =
-      genReferencesBlock(I.ChildRecords, "Records", I.Path);
+      genReferencesBlock(I.ChildRecords, "Records", BasePath);
   AppendVector(std::move(ChildRecords), Out);
 
   std::vector<std::unique_ptr<TagNode>> ChildFunctions =
-      genFunctionsBlock(I.ChildFunctions, CDCtx, I.Path);
+      genFunctionsBlock(I.ChildFunctions, CDCtx, BasePath);
   AppendVector(std::move(ChildFunctions), Out);
   std::vector<std::unique_ptr<TagNode>> ChildEnums =
       genEnumsBlock(I.ChildEnums, CDCtx);
   AppendVector(std::move(ChildEnums), Out);
 
   if (!I.ChildNamespaces.empty())
     InfoIndex.Children.emplace_back("Namespaces", "Namespaces");
   if (!I.ChildRecords.empty())
case InfoType::IT_function:
     MainContentNodes =
         genHTML(*static_cast<clang::doc::FunctionInfo *>(I), CDCtx, "");
     break;
   case InfoType::IT_default:
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "unexpected info type");
   }
 
-  HTMLFile F =
-      genInfoFile(InfoTitle, I->Path, MainContentNodes, InfoIndex, CDCtx);
+  HTMLFile F = genInfoFile(InfoTitle, I->getRelativeFilePath(""),
+                           MainContentNodes, InfoIndex, CDCtx);
   F.Render(OS);
 
   return llvm::Error::success();
 }
 
 static std::string getRefType(InfoType IT) {
   switch (IT) {
   case InfoType::IT_default:
static llvm::Error SerializeIndex(ClangDocContext &CDCtx) {
   }
   CDCtx.Idx.sort();
   llvm::json::OStream J(OS, 2);
   std::function<void(Index)> IndexToJSON = [&](Index I) {
     J.object([&] {
       J.attribute("USR", toHex(llvm::toStringRef(I.USR)));
       J.attribute("Name", I.Name);
       J.attribute("RefType", getRefType(I.RefType));
-      J.attribute("Path", I.Path);
+      J.attribute("Path", I.getRelativeFilePath(""));
       J.attributeArray("Children", [&] {
         for (const Index &C : I.Children)
           IndexToJSON(C);
       });
     });
   };
   OS << "var JsonIndex = `\n";
   IndexToJSON(CDCtx.Idx);

clang-tools-extra/clang-doc/MDGenerator.cpp

 }
 
 static void writeNewLine(raw_ostream &OS) { OS << "\n\n"; }
 
 static void writeHeader(const Twine &Text, unsigned int Num, raw_ostream &OS) {
   OS << std::string(Num, '#') + " " + Text << "\n\n";
 }
 
-static void writeFileDefinition(const Location &L, raw_ostream &OS) {
-  OS << genItalic("Defined at line " + std::to_string(L.LineNumber) + " of " +
-                  L.Filename)
-     << "\n\n";
+static void writeFileDefinition(const ClangDocContext &CDCtx, const Location &L,
+                                raw_ostream &OS) {
+
+  if (!CDCtx.RepositoryUrl) {
+    OS << "*Defined at " << L.Filename << "#" << std::to_string(L.LineNumber)
+       << "*";
+  } else {
+    OS << "*Defined at [" << L.Filename << "#" << std::to_string(L.LineNumber)
+       << "](" << StringRef{CDCtx.RepositoryUrl.getValue()}
+       << llvm::sys::path::relative_path(L.Filename) << "#"
+       << std::to_string(L.LineNumber) << ")"
+       << "*";
+  }
+  OS << "\n\n";
 }
 
 static void writeDescription(const CommentInfo &I, raw_ostream &OS) {
   if (I.Kind == "FullComment") {
     for (const auto &Child : I.Children)
       writeDescription(*Child, OS);
   } else if (I.Kind == "ParagraphComment") {
     for (const auto &Child : I.Children)
if (I.Kind == "FullComment") {
     writeLine("</" + I.Name + ">", OS);
   } else if (I.Kind == "TextComment") {
     OS << I.Text;
   } else {
     OS << "Unknown comment kind: " << I.Kind << ".\n\n";
   }
 }
 
-static void genMarkdown(const EnumInfo &I, llvm::raw_ostream &OS) {
+static void writeNameLink(const StringRef &CurrentPath, const Reference &R,
+                          llvm::raw_ostream &OS) {
+  llvm::SmallString<64> Path = R.getRelativeFilePath(CurrentPath);
+  // Paths in Markdown use POSIX separators.
+  llvm::sys::path::native(Path, llvm::sys::path::Style::posix);
+  llvm::sys::path::append(Path, llvm::sys::path::Style::posix,
+                          R.getFileBaseName() + ".md");
+  OS << "[" << R.Name << "](" << Path << ")";
+}
+
+static void genMarkdown(const ClangDocContext &CDCtx, const EnumInfo &I,
+                        llvm::raw_ostream &OS) {
   if (I.Scoped)
     writeLine("| enum class " + I.Name + " |", OS);
   else
     writeLine("| enum " + I.Name + " |", OS);
   writeLine("--", OS);
 
   std::string Buffer;
   llvm::raw_string_ostream Members(Buffer);
   if (!I.Members.empty())
     for (const auto &N : I.Members)
       Members << "| " << N << " |\n";
   writeLine(Members.str(), OS);
   if (I.DefLoc)
-    writeFileDefinition(I.DefLoc.getValue(), OS);
+    writeFileDefinition(CDCtx, I.DefLoc.getValue(), OS);
 
   for (const auto &C : I.Description)
     writeDescription(C, OS);
 }
 
-static void genMarkdown(const FunctionInfo &I, llvm::raw_ostream &OS) {
+static void genMarkdown(const ClangDocContext &CDCtx, const FunctionInfo &I,
+                        llvm::raw_ostream &OS) {
   std::string Buffer;
   llvm::raw_string_ostream Stream(Buffer);
   bool First = true;
   for (const auto &N : I.Params) {
     if (!First)
       Stream << ", ";
     Stream << N.Type.Name + " " + N.Name;
     First = false;
   }
   writeHeader(I.Name, 3, OS);
   std::string Access = getAccess(I.Access);
   if (Access != "")
     writeLine(genItalic(Access + " " + I.ReturnType.Type.Name + " " + I.Name +
                         "(" + Stream.str() + ")"),
               OS);
   else
     writeLine(genItalic(I.ReturnType.Type.Name + " " + I.Name + "(" +
                         Stream.str() + ")"),
               OS);
   if (I.DefLoc)
-    writeFileDefinition(I.DefLoc.getValue(), OS);
+    writeFileDefinition(CDCtx, I.DefLoc.getValue(), OS);
 
   for (const auto &C : I.Description)
     writeDescription(C, OS);
 }
 
-static void genMarkdown(const NamespaceInfo &I, llvm::raw_ostream &OS) {
+static void genMarkdown(const ClangDocContext &CDCtx, const NamespaceInfo &I,
+                        llvm::raw_ostream &OS) {
   if (I.Name == "")
     writeHeader("Global Namespace", 1, OS);
   else
     writeHeader("namespace " + I.Name, 1, OS);
   writeNewLine(OS);
 
   if (!I.Description.empty()) {
     for (const auto &C : I.Description)
       writeDescription(C, OS);
     writeNewLine(OS);
   }
 
+  llvm::SmallString<64> BasePath = I.getRelativeFilePath("");
+
   if (!I.ChildNamespaces.empty()) {
     writeHeader("Namespaces", 2, OS);
-    for (const auto &R : I.ChildNamespaces)
-      writeLine(R.Name, OS);
+    for (const auto &R : I.ChildNamespaces) {
+      OS << "* ";
+      writeNameLink(BasePath, R, OS);
+      OS << "\n";
+    }
     writeNewLine(OS);
   }
+
   if (!I.ChildRecords.empty()) {
     writeHeader("Records", 2, OS);
-    for (const auto &R : I.ChildRecords)
-      writeLine(R.Name, OS);
+    for (const auto &R : I.ChildRecords) {
+      OS << "* ";
+      writeNameLink(BasePath, R, OS);
+      OS << "\n";
+    }
     writeNewLine(OS);
   }
+
   if (!I.ChildFunctions.empty()) {
     writeHeader("Functions", 2, OS);
     for (const auto &F : I.ChildFunctions)
-      genMarkdown(F, OS);
+      genMarkdown(CDCtx, F, OS);
     writeNewLine(OS);
   }
   if (!I.ChildEnums.empty()) {
     writeHeader("Enums", 2, OS);
     for (const auto &E : I.ChildEnums)
-      genMarkdown(E, OS);
+      genMarkdown(CDCtx, E, OS);
     writeNewLine(OS);
   }
 }
 
-static void genMarkdown(const RecordInfo &I, llvm::raw_ostream &OS) {
+static void genMarkdown(const ClangDocContext &CDCtx, const RecordInfo &I,
+                        llvm::raw_ostream &OS) {
   writeHeader(getTagType(I.TagType) + " " + I.Name, 1, OS);
   if (I.DefLoc)
-    writeFileDefinition(I.DefLoc.getValue(), OS);
+    writeFileDefinition(CDCtx, I.DefLoc.getValue(), OS);
 
   if (!I.Description.empty()) {
     for (const auto &C : I.Description)
       writeDescription(C, OS);
     writeNewLine(OS);
   }
 
   std::string Parents = genReferenceList(I.Parents);
if (!I.ChildRecords.empty()) {
     writeHeader("Records", 2, OS);
     for (const auto &R : I.ChildRecords)
       writeLine(R.Name, OS);
     writeNewLine(OS);
   }
   if (!I.ChildFunctions.empty()) {
     writeHeader("Functions", 2, OS);
     for (const auto &F : I.ChildFunctions)
-      genMarkdown(F, OS);
+      genMarkdown(CDCtx, F, OS);
     writeNewLine(OS);
   }
   if (!I.ChildEnums.empty()) {
     writeHeader("Enums", 2, OS);
     for (const auto &E : I.ChildEnums)
-      genMarkdown(E, OS);
+      genMarkdown(CDCtx, E, OS);
     writeNewLine(OS);
   }
 }
 
+static void serializeReference(llvm::raw_fd_ostream &OS, Index &I, int Level) {
+  // Write out the heading level starting at ##
+  OS << "##" << std::string(Level, '#') << " ";
+  writeNameLink("", I, OS);
+  OS << "\n";
+}
+
+static llvm::Error serializeIndex(ClangDocContext &CDCtx) {
+  std::error_code FileErr;
+  llvm::SmallString<128> FilePath;
+  llvm::sys::path::native(CDCtx.OutDirectory, FilePath);
+  llvm::sys::path::append(FilePath, "all_files.md");
+  llvm::raw_fd_ostream OS(FilePath, FileErr, llvm::sys::fs::OF_None);
+  if (FileErr)
+    return llvm::createStringError(llvm::inconvertibleErrorCode(),
+                                   "error creating index file: " +
+                                       FileErr.message());
+
+  CDCtx.Idx.sort();
+  OS << "# All Files";
+  if (!CDCtx.ProjectName.empty())
+    OS << " for " << CDCtx.ProjectName;
+  OS << "\n\n";
+
+  for (auto C : CDCtx.Idx.Children)
+    serializeReference(OS, C, 0);
+
+  return llvm::Error::success();
+}
+
+static llvm::Error genIndex(ClangDocContext &CDCtx) {
+  std::error_code FileErr;
+  llvm::SmallString<128> FilePath;
+  llvm::sys::path::native(CDCtx.OutDirectory, FilePath);
+  llvm::sys::path::append(FilePath, "index.md");
+  llvm::raw_fd_ostream OS(FilePath, FileErr, llvm::sys::fs::OF_None);
+  if (FileErr)
+    return llvm::createStringError(llvm::inconvertibleErrorCode(),
+                                   "error creating index file: " +
+                                       FileErr.message());
+  CDCtx.Idx.sort();
+  OS << "# " << CDCtx.ProjectName << " C/C++ Reference\n\n";
+  for (auto C : CDCtx.Idx.Children) {
+    if (!C.Children.empty()) {
+      const char *Type;
+      switch (C.RefType) {
+      case InfoType::IT_namespace:
+        Type = "Namespace";
+        break;
+      case InfoType::IT_record:
+        Type = "Type";
+        break;
+      case InfoType::IT_enum:
+        Type = "Enum";
+        break;
+      case InfoType::IT_function:
+        Type = "Function";
+        break;
+      case InfoType::IT_default:
+        Type = "Other";
+      }
+      OS << "* " << Type << ": [" << C.Name << "](";
+      if (!C.Path.empty())
+        OS << C.Path << "/";
+      OS << C.Name << ")\n";
+    }
+  }
+  return llvm::Error::success();
+}
 /// Generator for Markdown documentation.
 class MDGenerator : public Generator {
 public:
   static const char *Format;
 
   llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS,
                                  const ClangDocContext &CDCtx) override;
+  llvm::Error createResources(ClangDocContext &CDCtx) override;
 };
 
 const char *MDGenerator::Format = "md";
 
 llvm::Error MDGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS,
                                             const ClangDocContext &CDCtx) {
   switch (I->IT) {
   case InfoType::IT_namespace:
-    genMarkdown(*static_cast<clang::doc::NamespaceInfo *>(I), OS);
+    genMarkdown(CDCtx, *static_cast<clang::doc::NamespaceInfo *>(I), OS);
     break;
   case InfoType::IT_record:
-    genMarkdown(*static_cast<clang::doc::RecordInfo *>(I), OS);
+    genMarkdown(CDCtx, *static_cast<clang::doc::RecordInfo *>(I), OS);
     break;
   case InfoType::IT_enum:
-    genMarkdown(*static_cast<clang::doc::EnumInfo *>(I), OS);
+    genMarkdown(CDCtx, *static_cast<clang::doc::EnumInfo *>(I), OS);
     break;
   case InfoType::IT_function:
-    genMarkdown(*static_cast<clang::doc::FunctionInfo *>(I), OS);
+    genMarkdown(CDCtx, *static_cast<clang::doc::FunctionInfo *>(I), OS);
     break;
   case InfoType::IT_default:
     return createStringError(llvm::inconvertibleErrorCode(),
                              "unexpected InfoType");
   }
   return llvm::Error::success();
 }
 
+llvm::Error MDGenerator::createResources(ClangDocContext &CDCtx) {
+  // Write an all_files.md
+  auto Err = serializeIndex(CDCtx);
+  if (Err)
+    return Err;
+
+  // Generate the index page.
+  Err = genIndex(CDCtx);
+  if (Err)
+    return Err;
+
+  return llvm::Error::success();
+}
+
 static GeneratorRegistry::Add<MDGenerator> MD(MDGenerator::Format,
                                               "Generator for MD output.");
 
-// This anchor is used to force the linker to link in the generated object file
-// and thus register the generator.
+// This anchor is used to force the linker to link in the generated object
+// file and thus register the generator.
 volatile int MDGeneratorAnchorSource = 0;
 
 } // namespace doc
 } // namespace clang

clang-tools-extra/clang-doc/Representation.h

struct Reference {
   bool operator==(const Reference &Other) const {
     return std::tie(USR, Name, RefType) ==
            std::tie(Other.USR, Other.Name, Other.RefType);
   }
 
   bool mergeable(const Reference &Other);
   void merge(Reference &&I);
 
+  /// Returns the path for this Reference relative to CurrentPath.
+  llvm::SmallString<64> getRelativeFilePath(const StringRef &CurrentPath) const;
+
+  /// Returns the basename that should be used for this Reference.
+  llvm::SmallString<16> getFileBaseName() const;
+
   SymbolID USR = SymbolID(); // Unique identifier for referenced decl
   SmallString<16> Name;      // Name of type (possibly unresolved).
   InfoType RefType = InfoType::IT_default; // Indicates the type of this
                                            // Reference (namespace, record,
                                            // function, enum, default).
   // Path of directory where the clang-doc generated file will be saved
   // (possibly unresolved)
   llvm::SmallString<128> Path;
struct Info {
   llvm::SmallString<128> Path;          // Path of directory where the clang-doc
                                         // generated file will be saved
 
   void mergeBase(Info &&I);
   bool mergeable(const Info &Other);
 
   llvm::SmallString<16> extractName() const;
 
+  /// Returns the file path for this Info relative to CurrentPath.
+  llvm::SmallString<64> getRelativeFilePath(const StringRef &CurrentPath) const;
+
+  /// Returns the basename that should be used for this Info.
+  llvm::SmallString<16> getFileBaseName() const;
+
   // Returns a reference to the parent scope (that is, the immediate parent
   // namespace or class in which this decl resides).
   llvm::Expected<Reference> getEnclosingScope();
 };
 
 // Info for namespaces.
 struct NamespaceInfo : public Info {
   NamespaceInfo() : Info(InfoType::IT_namespace) {}

clang-tools-extra/clang-doc/Representation.cpp

mergeInfos(std::vector<std::unique_ptr<Info>> &Values) {
   case InfoType::IT_function:
     return reduce<FunctionInfo>(Values);
   default:
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "unexpected info type");
   }
 }
 
+static llvm::SmallString<64>
+calculateRelativeFilePath(const InfoType &Type, const StringRef &Path,
+                          const StringRef &Name, const StringRef &CurrentPath) {
+  llvm::SmallString<64> FilePath;
+
+  if (CurrentPath != Path) {
+    // iterate back to the top
+    for (llvm::sys::path::const_iterator I =
+             llvm::sys::path::begin(CurrentPath);
+         I != llvm::sys::path::end(CurrentPath); ++I)
+      llvm::sys::path::append(FilePath, "..");
+    llvm::sys::path::append(FilePath, Path);
+  }
+
+  // Namespace references have a Path to the parent namespace, but
+  // the file is actually in the subdirectory for the namespace.
+  if (Type == doc::InfoType::IT_namespace)
+    llvm::sys::path::append(FilePath, Name);
+
+  return llvm::sys::path::relative_path(FilePath);
+}
+
+llvm::SmallString<64>
+Reference::getRelativeFilePath(const StringRef &CurrentPath) const {
+  return calculateRelativeFilePath(RefType, Path, Name, CurrentPath);
+}
+
+llvm::SmallString<16> Reference::getFileBaseName() const {
+  if (RefType == InfoType::IT_namespace)
+    return llvm::SmallString<16>("index");
+
+  return Name;
+}
+
+llvm::SmallString<64>
+Info::getRelativeFilePath(const StringRef &CurrentPath) const {
+  return calculateRelativeFilePath(IT, Path, extractName(), CurrentPath);
+}
+
+llvm::SmallString<16> Info::getFileBaseName() const {
+  if (IT == InfoType::IT_namespace)
+    return llvm::SmallString<16>("index");
+
+  return extractName();
+}
+
 bool Reference::mergeable(const Reference &Other) {
   return RefType == Other.RefType && USR == Other.USR;
 }
 
 void Reference::merge(Reference &&Other) {
   assert(mergeable(Other));
   if (Name.empty())
     Name = Other.Name;

clang-tools-extra/clang-doc/assets/index.js

while (Dir) {
     Dir = Dir.substring(0, Dir.lastIndexOf("/"));
     Result = append(Result, "..")
   }
   Result = append(Result, FilePath.substring(Dir.length))
   return Result;
 }
 
 function genLink(Ref, CurrentDirectory) {
   var Path = computeRelativePath(Ref.Path, CurrentDirectory);
+  if (Ref.RefType == "namespace")
+    Path = append(Path, "index.html");
+  else
     Path = append(Path, Ref.Name + ".html")
+
     ANode = document.createElement("a");
   ANode.setAttribute("href", Path);
   var TextNode = document.createTextNode(Ref.Name);
   ANode.appendChild(TextNode);
   return ANode;
 }
 
 function genHTMLOfIndex(Index, CurrentDirectory, IsOutermostList) {
   // Out will store the HTML elements that Index requires to be generated

clang-tools-extra/clang-doc/tool/ClangDocMain.cpp

Pool.async([&]() {
 
       auto Reduced = doc::mergeInfos(Infos);
       if (!Reduced) {
         llvm::errs() << llvm::toString(Reduced.takeError());
         return;
       }
 
       doc::Info *I = Reduced.get().get();
-      auto InfoPath = getInfoOutputFile(OutDirectory, I->Path, I->extractName(),
-                                        "." + Format);
+      auto InfoPath =
+          getInfoOutputFile(OutDirectory, I->getRelativeFilePath(""),
+                            I->getFileBaseName(), "." + Format);
       if (!InfoPath) {
         llvm::errs() << toString(InfoPath.takeError()) << "\n";
         Error = true;
         return;
       }
       std::error_code FileErr;
       llvm::raw_fd_ostream InfoOS(InfoPath.get(), FileErr,
                                   llvm::sys::fs::OF_None);
-      if (FileErr != OK) {
-        llvm::errs() << "Error opening info file: " << FileErr.message()
-                     << "\n";
+      if (FileErr) {
+        llvm::errs() << "Error opening info file " << InfoPath.get() << ": "
+                     << FileErr.message() << "\n";
         return;
       }
 
       IndexMutex.lock();
       // Add a reference to this Info in the Index
       clang::doc::Generator::addInfoToIndex(CDCtx.Idx, I);
       IndexMutex.unlock();
 

clang-tools-extra/test/clang-doc/single-file.cpp

 // RUN: rm -rf %t
 // RUN: mkdir %t
 // RUN: echo "" > %t/compile_flags.txt
 // RUN: cp "%s" "%t/test.cpp"
 // RUN: clang-doc --doxygen --executor=standalone -p %t %t/test.cpp -output=%t/docs
-// RUN: cat %t/docs/GlobalNamespace.yaml | FileCheck %s --check-prefix=CHECK
+// RUN: cat %t/docs/GlobalNamespace/index.yaml | FileCheck %s --check-prefix=CHECK
 // RUN: rm -rf %t
 
 void function(int x);
 
 void function(int x) {}
 
 // CHECK: ---
 // CHECK-NEXT: USR:             '{{[0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z]}}'
-// CHECK-NEXT: ChildFunctions:  
+// CHECK-NEXT: ChildFunctions:
 // CHECK-NEXT:   - USR:             '{{[0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z][0-9A-Z]}}'
 // CHECK-NEXT:    Name:            'function'
-// CHECK-NEXT:    DefLocation:     
+// CHECK-NEXT:    DefLocation:
 // CHECK-NEXT:      LineNumber:      [[@LINE-8]]
 // CHECK-NEXT:      Filename:        '{{.*}}
-// CHECK-NEXT:    Location:        
+// CHECK-NEXT:    Location:
 // CHECK-NEXT:      - LineNumber:      [[@LINE-13]]
 // CHECK-NEXT:        Filename:        '{{.*}}'
-// CHECK-NEXT:    Params:          
-// CHECK-NEXT:      - Type:            
+// CHECK-NEXT:    Params:
+// CHECK-NEXT:      - Type:
 // CHECK-NEXT:          Name:            'int'
 // CHECK-NEXT:        Name:            'x'
-// CHECK-NEXT:    ReturnType:      
-// CHECK-NEXT:      Type:            
+// CHECK-NEXT:    ReturnType:
+// CHECK-NEXT:      Type:
 // CHECK-NEXT:        Name:            'void'
 // CHECK-NEXT:...

clang-tools-extra/unittests/clang-doc/HTMLGeneratorTest.cpp

TEST(HTMLGeneratorTest, emitNamespaceHTML) {
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
   ClangDocContext CDCtx = getClangDocContext({"user-provided-stylesheet.css"});
   auto Err = G->generateDocForInfo(&I, Actual, CDCtx);
   assert(!Err);
   std::string Expected = R"raw(<!DOCTYPE html>
 <meta charset="utf-8"/>
 <title>namespace Namespace</title>
-<link rel="stylesheet" href="clang-doc-default-stylesheet.css"/>
-<link rel="stylesheet" href="user-provided-stylesheet.css"/>
-<script src="index.js"></script>
+<link rel="stylesheet" href="../clang-doc-default-stylesheet.css"/>
+<link rel="stylesheet" href="../user-provided-stylesheet.css"/>
+<script src="../index.js"></script>
 <header id="project-title">test-project</header>
 <main>
-  <div id="sidebar-left" path="" class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left"></div>
+  <div id="sidebar-left" path="Namespace" class="col-xs-6 col-sm-3 col-md-2 sidebar sidebar-offcanvas-left"></div>
   <div id="main-content" class="col-xs-12 col-sm-9 col-md-8 main-content">
     <h1>namespace Namespace</h1>
     <h2 id="Namespaces">Namespaces</h2>
     <ul>
       <li>
-        <a href="Namespace/ChildNamespace.html">ChildNamespace</a>
+        <a href="ChildNamespace/index.html">ChildNamespace</a>
       </li>
     </ul>
     <h2 id="Records">Records</h2>
     <ul>
       <li>
-        <a href="Namespace/ChildStruct.html">ChildStruct</a>
+        <a href="ChildStruct.html">ChildStruct</a>
       </li>
     </ul>
     <h2 id="Functions">Functions</h2>
     <div>
       <h3 id="0000000000000000000000000000000000000000">OneFunction</h3>
       <p>OneFunction()</p>
     </div>
     <h2 id="Enums">Enums</h2>
<p>
       Inherits from 
       <a href="../../../path/to/F.html">F</a>
       , G
     </p>
     <h2 id="Members">Members</h2>
     <ul>
       <li>
         private 
-        <a href="../int.html">int</a>
+        <a href="../../../X/Y/int.html">int</a>
          X
       </li>
     </ul>
     <h2 id="Records">Records</h2>
     <ul>
       <li>
-        <a href="r/ChildStruct.html">ChildStruct</a>
+        <a href="../../../X/Y/Z/r/ChildStruct.html">ChildStruct</a>
       </li>
     </ul>
     <h2 id="Functions">Functions</h2>
     <div>
       <h3 id="0000000000000000000000000000000000000000">OneFunction</h3>
       <p>public OneFunction()</p>
     </div>
     <h2 id="Enums">Enums</h2>

clang-tools-extra/unittests/clang-doc/MDGeneratorTest.cpp

TEST(MDGeneratorTest, emitNamespaceMD) {
   auto Err = G->generateDocForInfo(&I, Actual, ClangDocContext());
   assert(!Err);
   std::string Expected = R"raw(# namespace Namespace
 
 
 
 ## Namespaces
 
-ChildNamespace
-
+* [ChildNamespace](../ChildNamespace/index.md)
 
 
 ## Records
 
-ChildStruct
-
+* [ChildStruct](../ChildStruct.md)
 
 
 ## Functions
 
 ### OneFunction
 
 * OneFunction()*
 
TEST(MDGeneratorTest, emitRecordMD) {
   auto G = getMDGenerator();
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
   auto Err = G->generateDocForInfo(&I, Actual, ClangDocContext());
   assert(!Err);
   std::string Expected = R"raw(# class r
 
-*Defined at line 10 of test.cpp*
+*Defined at test.cpp#10*
 
 Inherits from F, G
 
 
 
 ## Members
 
 private int X
TEST(MDGeneratorTest, emitFunctionMD) {
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
   auto Err = G->generateDocForInfo(&I, Actual, ClangDocContext());
   assert(!Err);
   std::string Expected = R"raw(### f
 
 *void f(int P)*
 
-*Defined at line 10 of test.cpp*
+*Defined at test.cpp#10*
 
 )raw";
 
   EXPECT_EQ(Expected, Actual.str());
 }
 
 TEST(MDGeneratorTest, emitEnumMD) {
   EnumInfo I;
TEST(MDGeneratorTest, emitEnumMD) {
   assert(!Err);
   std::string Expected = R"raw(| enum class e |
 
 --
 
 | X |
 
 
-*Defined at line 10 of test.cpp*
+*Defined at test.cpp#10*
 
 )raw";
 
   EXPECT_EQ(Expected, Actual.str());
 }
 
 TEST(MDGeneratorTest, emitCommentMD) {
   FunctionInfo I;
TEST(MDGeneratorTest, emitCommentMD) {
   llvm::raw_string_ostream Actual(Buffer);
   auto Err = G->generateDocForInfo(&I, Actual, ClangDocContext());
   assert(!Err);
   std::string Expected =
       R"raw(### f
 
 *void f(int I, int J)*
 
-*Defined at line 10 of test.cpp*
+*Defined at test.cpp#10*
 
 
 
  Brief description.
 
  Extended description that continues onto the next line.
 
 <ul "class=test">