[clang-doc] Add a breadcrumb navigation bar (llvm#173297)

This patch adds a breadcrumb navigation bar to the `<navbar>` element. Now, you can navigate between the different scopes of a record or namespace. This is done by keeping track of a Decl's parent Decl through its USR. That allows us to traverse the set of `Info`s through a directed graph during JSON generation to create `Context`s. A context is just a `Reference` that holds a relative path to a scope's file from a particular `Info`.

Author: evelez7

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

@@ -159,6 +159,8 @@ static llvm::Error parseRecord(const Record &R, unsigned ID,
     return decodeRecord(R, I->Name, Blob);
   case NAMESPACE_PATH:
     return decodeRecord(R, I->Path, Blob);
+  case NAMESPACE_PARENT_USR:
+    return decodeRecord(R, I->ParentUSR, Blob);
   default:
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "invalid field for NamespaceInfo");
@@ -184,6 +186,8 @@ static llvm::Error parseRecord(const Record &R, unsigned ID,
     return decodeRecord(R, I->IsTypeDef, Blob);
   case RECORD_MANGLED_NAME:
     return decodeRecord(R, I->MangledName, Blob);
+  case RECORD_PARENT_USR:
+    return decodeRecord(R, I->ParentUSR, Blob);
   default:
     return llvm::createStringError(llvm::inconvertibleErrorCode(),
                                    "invalid field for RecordInfo");

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

@@ -174,6 +174,7 @@ static const llvm::IndexedMap<RecordIdDsc, RecordIdToIndexFunctor>
           {NAMESPACE_USR, {"USR", &genSymbolIdAbbrev}},
           {NAMESPACE_NAME, {"Name", &genStringAbbrev}},
           {NAMESPACE_PATH, {"Path", &genStringAbbrev}},
+          {NAMESPACE_PARENT_USR, {"ParentUSR", &genSymbolIdAbbrev}},
           {ENUM_USR, {"USR", &genSymbolIdAbbrev}},
           {ENUM_NAME, {"Name", &genStringAbbrev}},
           {ENUM_DEFLOCATION, {"DefLocation", &genLocationAbbrev}},
@@ -190,6 +191,7 @@ static const llvm::IndexedMap<RecordIdDsc, RecordIdToIndexFunctor>
           {RECORD_TAG_TYPE, {"TagType", &genIntAbbrev}},
           {RECORD_IS_TYPE_DEF, {"IsTypeDef", &genBoolAbbrev}},
           {RECORD_MANGLED_NAME, {"MangledName", &genStringAbbrev}},
+          {RECORD_PARENT_USR, {"ParentUSR", &genSymbolIdAbbrev}},
           {BASE_RECORD_USR, {"USR", &genSymbolIdAbbrev}},
           {BASE_RECORD_NAME, {"Name", &genStringAbbrev}},
           {BASE_RECORD_PATH, {"Path", &genStringAbbrev}},
@@ -270,12 +272,12 @@ static const std::vector<std::pair<BlockId, std::vector<RecordId>>>
          {TYPEDEF_USR, TYPEDEF_NAME, TYPEDEF_DEFLOCATION, TYPEDEF_IS_USING}},
         // Namespace Block
         {BI_NAMESPACE_BLOCK_ID,
-         {NAMESPACE_USR, NAMESPACE_NAME, NAMESPACE_PATH}},
+         {NAMESPACE_USR, NAMESPACE_NAME, NAMESPACE_PATH, NAMESPACE_PARENT_USR}},
         // Record Block
         {BI_RECORD_BLOCK_ID,
          {RECORD_USR, RECORD_NAME, RECORD_PATH, RECORD_DEFLOCATION,
           RECORD_LOCATION, RECORD_TAG_TYPE, RECORD_IS_TYPE_DEF,
-          RECORD_MANGLED_NAME}},
+          RECORD_MANGLED_NAME, RECORD_PARENT_USR}},
         // BaseRecord Block
         {BI_BASE_RECORD_BLOCK_ID,
          {BASE_RECORD_USR, BASE_RECORD_NAME, BASE_RECORD_PATH,
@@ -570,6 +572,7 @@ void ClangDocBitcodeWriter::emitBlock(const NamespaceInfo &I) {
   emitRecord(I.USR, NAMESPACE_USR);
   emitRecord(I.Name, NAMESPACE_NAME);
   emitRecord(I.Path, NAMESPACE_PATH);
+  emitRecord(I.ParentUSR, NAMESPACE_PARENT_USR);
   for (const auto &N : I.Namespace)
     emitBlock(N, FieldId::F_namespace);
   for (const auto &CI : I.Description)
@@ -624,6 +627,7 @@ void ClangDocBitcodeWriter::emitBlock(const RecordInfo &I) {
   emitRecord(I.Name, RECORD_NAME);
   emitRecord(I.Path, RECORD_PATH);
   emitRecord(I.MangledName, RECORD_MANGLED_NAME);
+  emitRecord(I.ParentUSR, RECORD_PARENT_USR);
   for (const auto &N : I.Namespace)
     emitBlock(N, FieldId::F_namespace);
   for (const auto &CI : I.Description)

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

@@ -108,6 +108,7 @@ enum RecordId {
   NAMESPACE_USR,
   NAMESPACE_NAME,
   NAMESPACE_PATH,
+  NAMESPACE_PARENT_USR,
   ENUM_USR,
   ENUM_NAME,
   ENUM_DEFLOCATION,
@@ -124,6 +125,7 @@ enum RecordId {
   RECORD_TAG_TYPE,
   RECORD_IS_TYPE_DEF,
   RECORD_MANGLED_NAME,
+  RECORD_PARENT_USR,
   BASE_RECORD_USR,
   BASE_RECORD_NAME,
   BASE_RECORD_PATH,

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

@@ -278,6 +278,64 @@ static Object serializeComment(const CommentInfo &I, Object &Description) {
   llvm_unreachable("Unknown comment kind encountered.");
 }
 
+/// Creates Contexts for namespaces and records to allow for navigation.
+static void generateContext(const Info &I, Object &Obj) {
+  json::Value ContextArray = json::Array();
+  auto &ContextArrayRef = *ContextArray.getAsArray();
+  ContextArrayRef.reserve(I.Contexts.size());
+
+  std::string CurrentRelativePath;
+  bool PreviousRecord = false;
+  for (const auto &Current : I.Contexts) {
+    json::Value ContextVal = Object();
+    Object &Context = *ContextVal.getAsObject();
+    serializeReference(Current, Context);
+
+    if (ContextArrayRef.empty() && I.IT == InfoType::IT_record) {
+      if (Current.DocumentationFileName == "index") {
+        // If the record's immediate context is a namespace, then the
+        // "index.html" is in the same directory.
+        PreviousRecord = false;
+        Context["RelativePath"] = "./";
+      } else {
+        // If the immediate context is a record, then the file is one level
+        // above
+        PreviousRecord = true;
+        CurrentRelativePath += "../";
+        Context["RelativePath"] = CurrentRelativePath;
+      }
+      ContextArrayRef.push_back(ContextVal);
+      continue;
+    }
+
+    if (PreviousRecord && (Current.DocumentationFileName == "index")) {
+      // If the previous Context was a record then we already went up a level,
+      // so the current namespace index is in the same directory.
+      PreviousRecord = false;
+    } else if (Current.DocumentationFileName != "index") {
+      // If the current Context is a record but the previous wasn't a record,
+      // then the namespace index is located one level above.
+      PreviousRecord = true;
+      CurrentRelativePath += "../";
+    } else {
+      // The current Context is a namespace and so was the previous Context.
+      PreviousRecord = false;
+      CurrentRelativePath += "../";
+      // If this namespace is the global namespace, then its documentation
+      // name needs to be changed to link correctly.
+      if (Current.QualName == "GlobalNamespace" && Current.RelativePath != "./")
+        Context["DocumentationFileName"] =
+            SmallString<16>("GlobalNamespace/index");
+    }
+    Context["RelativePath"] = CurrentRelativePath;
+    ContextArrayRef.insert(ContextArrayRef.begin(), ContextVal);
+  }
+
+  ContextArrayRef.back().getAsObject()->insert({"End", true});
+  Obj["Contexts"] = ContextArray;
+  Obj["HasContexts"] = true;
+}
+
 static void
 serializeCommonAttributes(const Info &I, json::Object &Obj,
                           const std::optional<StringRef> RepositoryUrl) {
@@ -323,6 +381,9 @@ serializeCommonAttributes(const Info &I, json::Object &Obj,
       Obj["Location"] =
           serializeLocation(Symbol->DefLoc.value(), RepositoryUrl);
   }
+
+  if (!I.Contexts.empty())
+    generateContext(I, Obj);
 }
 
 static void serializeReference(const Reference &Ref, Object &ReferenceObj) {
@@ -335,7 +396,7 @@ static void serializeReference(const Reference &Ref, Object &ReferenceObj) {
 
     // If the reference is a nested class it will be put into a folder named
     // after the parent class. We can get that name from the path's stem.
-    if (Ref.Path != "GlobalNamespace")
+    if (Ref.Path != "GlobalNamespace" && !Ref.Path.empty())
       ReferenceObj["PathStem"] = sys::path::stem(Ref.Path);
   }
 }
@@ -730,6 +791,29 @@ static Error serializeIndex(const ClangDocContext &CDCtx, StringRef RootDir) {
   return Error::success();
 }
 
+static void serializeContexts(Info *I,
+                              StringMap<std::unique_ptr<Info>> &Infos) {
+  if (I->USR == GlobalNamespaceID)
+    return;
+  auto ParentUSR = I->ParentUSR;
+
+  while (true) {
+    auto &ParentInfo = Infos.at(llvm::toHex(ParentUSR));
+
+    if (ParentInfo && ParentInfo->USR == GlobalNamespaceID) {
+      Context GlobalRef(ParentInfo->USR, "Global Namespace",
+                        InfoType::IT_namespace, "GlobalNamespace", "",
+                        SmallString<16>("index"));
+      I->Contexts.push_back(GlobalRef);
+      return;
+    }
+
+    Context ParentRef(*ParentInfo);
+    I->Contexts.push_back(ParentRef);
+    ParentUSR = ParentInfo->ParentUSR;
+  }
+}
+
 Error JSONGenerator::generateDocumentation(
     StringRef RootDir, llvm::StringMap<std::unique_ptr<doc::Info>> Infos,
     const ClangDocContext &CDCtx, std::string DirName) {
@@ -763,9 +847,12 @@ Error JSONGenerator::generateDocumentation(
     if (FileErr)
       return createFileError("cannot open file " + Group.getKey(), FileErr);
 
-    for (const auto &Info : Group.getValue())
+    for (const auto &Info : Group.getValue()) {
+      if (Info->IT == InfoType::IT_record || Info->IT == InfoType::IT_namespace)
+        serializeContexts(Info, Infos);
       if (Error Err = generateDocForInfo(Info, InfoOS, CDCtx))
         return Err;
+    }
   }
 
   return serializeIndex(CDCtx, RootDir);

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

@@ -273,6 +273,10 @@ void Info::mergeBase(Info &&Other) {
   llvm::sort(Description);
   auto Last = llvm::unique(Description);
   Description.erase(Last, Description.end());
+  if (ParentUSR == EmptySID)
+    ParentUSR = Other.ParentUSR;
+  if (DocumentationFileName.empty())
+    DocumentationFileName = Other.DocumentationFileName;
 }
 
 bool Info::mergeable(const Info &Other) {

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

@@ -165,6 +165,16 @@ struct Reference {
   SmallString<16> DocumentationFileName;
 };
 
+// A Context is a reference that holds a relative path from a certain Info's
+// location.
+struct Context : public Reference {
+  Context(SymbolID USR, StringRef Name, InfoType IT, StringRef QualName,
+          StringRef Path, SmallString<16> DocumentationFileName)
+      : Reference(USR, Name, IT, QualName, Path, DocumentationFileName) {}
+  explicit Context(const Info &I);
+  SmallString<128> RelativePath;
+};
+
 // Holds the children of a record or namespace.
 struct ScopeChildren {
   // Namespaces and Records are references because they will be properly
@@ -356,13 +366,21 @@ struct Info {
   // Unique identifier for the decl described by this Info.
   SymbolID USR = SymbolID();
 
+  // Currently only used for namespaces and records.
+  SymbolID ParentUSR = SymbolID();
+
   // InfoType of this particular Info.
   InfoType IT = InfoType::IT_default;
 
   // Comment description of this decl.
   std::vector<CommentInfo> Description;
+
+  SmallVector<Context, 4> Contexts;
 };
 
+inline Context::Context(const Info &I)
+    : Reference(I.USR, I.Name, I.IT, I.Name, I.Path, I.DocumentationFileName) {}
+
 // Info for namespaces.
 struct NamespaceInfo : public Info {
   NamespaceInfo(SymbolID USR = SymbolID(), StringRef Name = StringRef(),

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

@@ -697,10 +697,46 @@ static TemplateParamInfo convertTemplateArgToInfo(const clang::Decl *D,
   return TemplateParamInfo(Str);
 }
 
+// Check if the DeclKind is one for which we support contextual relationships.
+// There might be other ContextDecls, like blocks, that we currently don't
+// handle at all.
+static bool isSupportedContext(Decl::Kind DeclKind) {
+  switch (DeclKind) {
+  case Decl::Kind::Record:
+  case Decl::Kind::CXXRecord:
+  case Decl::Kind::ClassTemplateSpecialization:
+  case Decl::Kind::ClassTemplatePartialSpecialization:
+  case Decl::Kind::Namespace:
+    return true;
+  default:
+    return false;
+  }
+}
+
+static void findParent(Info &I, const Decl *D) {
+  assert(D && "Invalid Decl");
+
+  // Only walk up contexts if D is a record or namespace.
+  if (!isSupportedContext(D->getKind()))
+    return;
+
+  const DeclContext *ParentCtx = dyn_cast<DeclContext>(D)->getLexicalParent();
+  while (ParentCtx) {
+    if (isSupportedContext(ParentCtx->getDeclKind())) {
+      // Break when we reach the first record or namespace.
+      I.ParentUSR = getUSRForDecl(dyn_cast<Decl>(ParentCtx));
+      break;
+    }
+    ParentCtx = ParentCtx->getParent();
+  }
+}
+
 template <typename T>
 static void populateInfo(Info &I, const T *D, const FullComment *C,
                          bool &IsInAnonymousNamespace) {
   I.USR = getUSRForDecl(D);
+  findParent(I, D);
+
   if (auto ConversionDecl = dyn_cast_or_null<CXXConversionDecl>(D);
       ConversionDecl && ConversionDecl->getConversionType()
                             .getTypePtr()

clang-tools-extra/clang-doc/assets/clang-doc-mustache.css

@@ -112,7 +112,6 @@ body, html {
     width: 100%;
     top: 0;
     left: 0;
-    height: 60px; /* Adjust as needed */
     color: white;
     display: flex;
     align-items: center;
@@ -255,6 +254,38 @@ body, html {
     color:var(--text1)
 }
 
+.navbar-breadcrumb-container {
+    position: absolute;
+    top: 60px;
+    left: 0;
+    width: 100%;
+    background: var(--surface2);
+    padding: 0.5rem 1rem;
+    display: flex;
+    gap: 0.5rem;
+    border-bottom: 1px solid var(--text2);
+    box-sizing: border-box;
+    border-top: 1px solid var(--text2);
+    border-bottom: 1px solid var(--text2);
+}
+
+.navbar-breadcrumb-item {
+    padding: 0.25rem 0.75rem;
+    background: var(--surface1);
+    border: 1px solid var(--text2);
+    border-radius: 4px;
+    color: var(--text1);
+    font-size: 0.9rem;
+    white-space: nowrap;
+}
+
+.navbar-breadcrumb-item:hover {
+    background: var(--brand);
+    color: var(--text1-inverse);
+    border-color: var(--brand);
+    cursor: pointer;
+}
+
 .hero__container {
     margin-top:1rem;
     display:flex;
@@ -317,9 +348,7 @@ body, html {
     max-width: 2048px;
     margin-left:auto;
     margin-right:auto;
-    margin-top:0;
     margin-bottom: 1rem;
-    padding:1rem 2rem
 }
 
 @media(max-width:768px) {
@@ -404,16 +433,17 @@ body, html {
 
 .sidebar {
     width: 250px;
-    top: 60px;
     left: 0;
-    height: 100%;
+    top: 60px;
+    bottom: 0;
     position: fixed;
     background-color: var(--surface1);
     display: flex;
     border-left: 1px solid var(--text2);
     flex-direction: column;
     overflow-y: auto;
     scrollbar-width: thin;
+    flex-shrink: 0;
 }
 
 .sidebar h2 {
@@ -445,8 +475,8 @@ body, html {
 
 /* Content */
 .content {
+    top: 60px;
     background-color: var(--text1-inverse);
-    padding: 20px;
     left: 250px;
     position: relative;
     width: calc(100% - 250px);