[clang-doc] Add stylesheet to generated html docs

[DiegoAstiazaran]

Summary

A default css stylesheet is included for docs generated in html format.

[juliehockett]

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

255–280

Could you use llvm::sys::fs::copy_file here? https://llvm.org/doxygen/namespacellvm_1_1sys_1_1fs.html#abe768b38d21bfc2bc91a1c1d09cd84de

[juliehockett]

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

256

Eventually, we'll want to make this a configurable thing via a flag, but that can be done in another patch.

[DiegoAstiazaran]

Use llvm::sys::fs::copy_file to copy css file.

[juliehockett]

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

252

On second thought, can you create a virtual method to the Generator along the lines of Generator::createResources(ClangDocContext ctx), which would be a no-op for the YAML and MD generators atm and for the HTML generator would encapsulate this logic? I'd rather not have it in the main tool file, since it is generator-specific.

[DiegoAstiazaran]

Move the generation of css stylesheet to a function inside the HTMLGenerator.
A virtual function createResources was declared for Generator class. This is no-op for the YAML and MD generators. For the HTML it contains the generation of css stylesheet.

[DiegoAstiazaran]

Move the CSS file to share/clang and read it from there, instead of trying to read it from the file that's with the source code, that only worked when run locally.

[jakehehrlich]

I'm blindly accepting the CSS but all other code looks fine. I still have that chrome bug where I can't LGTM sometimes but consider this reviewed and accepted by me as well

[juliehockett]

LGTM

[juliehockett]

LGTM

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

 // Abstract base class for generators.
 // This is expected to be implemented and exposed via the GeneratorRegistry.
 class Generator {
 public:
   virtual ~Generator() = default;
 
   // Write out the decl info in the specified format.
   virtual llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS) = 0;
+  virtual bool createResources(ClangDocContext CDCtx) = 0;
 };
 
 typedef llvm::Registry<Generator> GeneratorRegistry;
 
 llvm::Expected<std::unique_ptr<Generator>>
 findGeneratorByName(llvm::StringRef Format);
 
 std::string getAccess(AccessSpecifier AS);
 
 std::string getTagType(TagTypeKind AS);
 
 } // namespace doc
 } // namespace clang
 
 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_GENERATOR_H

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

enum TagType {
     TAG_DIV,
     TAG_H1,
     TAG_H2,
     TAG_H3,
     TAG_P,
     TAG_UL,
     TAG_LI,
     TAG_A,
+    TAG_LINK,
   };
 
   HTMLTag() = default;
   constexpr HTMLTag(TagType Value) : Value(Value) {}
 
   operator TagType() const { return Value; }
   operator bool() = delete;
 
struct HTMLFile {
   }
 };
 
 } // namespace
 
 bool HTMLTag::IsSelfClosing() const {
   switch (Value) {
   case HTMLTag::TAG_META:
+  case HTMLTag::TAG_LINK:
     return true;
   case HTMLTag::TAG_TITLE:
   case HTMLTag::TAG_DIV:
   case HTMLTag::TAG_H1:
   case HTMLTag::TAG_H2:
   case HTMLTag::TAG_H3:
   case HTMLTag::TAG_P:
   case HTMLTag::TAG_UL:
   case HTMLTag::TAG_LI:
   case HTMLTag::TAG_A:
     return false;
   }
 }
 
 bool HTMLTag::HasInlineChildren() const {
   switch (Value) {
   case HTMLTag::TAG_META:
   case HTMLTag::TAG_TITLE:
   case HTMLTag::TAG_H1:
   case HTMLTag::TAG_H2:
   case HTMLTag::TAG_H3:
   case HTMLTag::TAG_LI:
   case HTMLTag::TAG_A:
+  case HTMLTag::TAG_LINK:
     return true;
   case HTMLTag::TAG_DIV:
   case HTMLTag::TAG_P:
   case HTMLTag::TAG_UL:
     return false;
   }
 }
 
llvm::SmallString<16> HTMLTag::ToString() const {
   case HTMLTag::TAG_P:
     return llvm::SmallString<16>("p");
   case HTMLTag::TAG_UL:
     return llvm::SmallString<16>("ul");
   case HTMLTag::TAG_LI:
     return llvm::SmallString<16>("li");
   case HTMLTag::TAG_A:
     return llvm::SmallString<16>("a");
+  case HTMLTag::TAG_LINK:
+    return llvm::SmallString<16>("link");
   }
 }
 
 void TextNode::Render(llvm::raw_ostream &OS, int IndentationLevel) {
   if (Indented)
     OS.indent(IndentationLevel * 2);
   OS << Text;
 }

 }
 
 /// Generator for HTML documentation.
 class HTMLGenerator : public Generator {
 public:
   static const char *Format;
 
   llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS) override;
+  bool createResources(ClangDocContext CDCtx) override;
 };
 
 const char *HTMLGenerator::Format = "html";
 
 llvm::Error HTMLGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS) {
   HTMLFile F;
 
   auto MetaNode = llvm::make_unique<TagNode>(HTMLTag::TAG_META);
llvm::Error HTMLGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS) {
   }
   case InfoType::IT_default:
     return llvm::make_error<llvm::StringError>("Unexpected info type.\n",
                                                llvm::inconvertibleErrorCode());
   }
 
   F.Children.emplace_back(
       llvm::make_unique<TagNode>(HTMLTag::TAG_TITLE, InfoTitle));
+  auto LinkNode = llvm::make_unique<TagNode>(HTMLTag::TAG_LINK);
+  LinkNode->Attributes.try_emplace("rel", "stylesheet");
+  SmallString<128> StylesheetPath = computeRelativePath("", I->Path);
+  llvm::sys::path::append(StylesheetPath, "clang-doc-default-stylesheet.css");
+  LinkNode->Attributes.try_emplace("href", StylesheetPath);
+  F.Children.emplace_back(std::move(LinkNode));
   F.Children.emplace_back(std::move(MainContentNode));
   F.Render(OS);
 
   return llvm::Error::success();
 }
 
+bool HTMLGenerator::createResources(ClangDocContext CDCtx) {
+  llvm::outs() << "Generating stylesheet for docs...\n";
+  llvm::SmallString<128> StylesheetPathWrite;
+  llvm::sys::path::native(CDCtx.OutDirectory, StylesheetPathWrite);
+  llvm::sys::path::append(StylesheetPathWrite,
+                          "clang-doc-default-stylesheet.css");
+  llvm::SmallString<128> StylesheetPathRead;
+  llvm::sys::path::native(CDCtx.ClangDocPath, StylesheetPathRead);
+  StylesheetPathRead = llvm::sys::path::parent_path(StylesheetPathRead);
+  llvm::sys::path::append(StylesheetPathRead, "..", "share", "clang",
+                          "clang-doc-default-stylesheet.css");
+  std::error_code OK;
+  std::error_code FileErr =
+      llvm::sys::fs::copy_file(StylesheetPathRead, StylesheetPathWrite);
+  if (FileErr != OK) {
+    llvm::errs() << "Error creating stylesheet file: " << FileErr.message()
+                 << "\n";
+    return false;
+  }
+  return true;
+}
+
 static GeneratorRegistry::Add<HTMLGenerator> HTML(HTMLGenerator::Format,
                                                   "Generator for HTML output.");
 
 // This anchor is used to force the linker to link in the generated object
 // file and thus register the generator.
 volatile int HTMLGeneratorAnchorSource = 0;
 
 } // namespace doc
 } // namespace clang

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

 }
 
 /// Generator for Markdown documentation.
 class MDGenerator : public Generator {
 public:
   static const char *Format;
 
   llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS) override;
+  bool createResources(ClangDocContext CDCtx) override { return true; }
 };
 
 const char *MDGenerator::Format = "md";
 
 llvm::Error MDGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS) {
   switch (I->IT) {
   case InfoType::IT_namespace:
     genMarkdown(*static_cast<clang::doc::NamespaceInfo *>(I), OS);

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

 // This assumes that all infos in the vector are of the same type, and will fail
 // if they are different.
 llvm::Expected<std::unique_ptr<Info>>
 mergeInfos(std::vector<std::unique_ptr<Info>> &Values);
 
 struct ClangDocContext {
   tooling::ExecutionContext *ECtx;
   bool PublicOnly;
+  std::string OutDirectory;
+  std::string ClangDocPath;
 };
 
 } // namespace doc
 } // namespace clang
 
 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANG_DOC_REPRESENTATION_H

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

 // namesapce B {
 //
 // class C {};
 //
 // }
 // }
 llvm::SmallString<128>
 getInfoRelativePath(const llvm::SmallVectorImpl<doc::Reference> &Namespaces) {
-  std::error_code OK;
   llvm::SmallString<128> Path;
   for (auto R = Namespaces.rbegin(), E = Namespaces.rend(); R != E; ++R)
     llvm::sys::path::append(Path, R->Name);
   return Path;
 }
 
 llvm::SmallString<128> getInfoRelativePath(const Decl *D) {
   llvm::SmallVector<Reference, 4> Namespaces;

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

 namespace doc {
 
 /// Generator for YAML documentation.
 class YAMLGenerator : public Generator {
 public:
   static const char *Format;
 
   llvm::Error generateDocForInfo(Info *I, llvm::raw_ostream &OS) override;
+  bool createResources(ClangDocContext CDCtx) override { return true; }
 };
 
 const char *YAMLGenerator::Format = "yaml";
 
 llvm::Error YAMLGenerator::generateDocForInfo(Info *I, llvm::raw_ostream &OS) {
   llvm::yaml::Output InfoYAML(OS);
   switch (I->IT) {
   case InfoType::IT_namespace:

clang-tools-extra/clang-doc/stylesheets/clang-doc-default-stylesheet.css

+body,div {
+  margin: 0;
+  padding: 0;
+}
+
+body[no-overflow] {
+  overflow: hidden;
+}
+
+li>p:first-child {
+  margin-top: 0;
+}
+
+li>p:last-child {
+  margin-bottom: 0;
+}
+
+html {
+  -webkit-box-sizing: border-box;
+  box-sizing: border-box;
+}
+
+*,*::before,*::after {
+  -webkit-box-sizing: inherit;
+  box-sizing: inherit;
+}
+
+body,html {
+  color: #202124;
+  font: 400 16px/24px Roboto,sans-serif;
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-font-smoothing: antialiased;
+  height: 100%;
+  margin: 36px;
+  -webkit-text-size-adjust: 100%;
+  -moz-text-size-adjust: 100%;
+  -ms-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+body[devsite-framebox] {
+  overflow: hidden;
+  padding: 20px;
+}
+
+body[sitemask--active] {
+  overflow: hidden;
+}
+
+p {
+  margin: 16px 0;
+  padding: 0;
+}
+
+:link,:visited {
+  color: #039be5;
+  outline: 0;
+  text-decoration: none;
+}
+
+ul {
+  margin: 0;
+  padding-left: 40px;
+}
+
+ul {
+  list-style: disc outside;
+}
+
+li,li p {
+  margin: 12px 0;
+  padding: 0;
+}
+
+*[visually-hidden] {
+  opacity: 0 !important;
+  pointer-events: none !important;
+  visibility: hidden !important;
+}
+
+*[hidden] {
+  display: none !important;
+}
+
+[render-hidden] {
+  display: inline !important;
+  position: absolute !important;
+  visibility: hidden !important;
+}
+
+*[no-scroll] {
+  overflow: hidden;
+}
+
+@supports (display: flex) {
+  body[ready] .devsite-wrapper {
+    display: -webkit-box;
+    display: -ms-flexbox;
+    display: flex;
+    -webkit-box-orient: vertical;
+    -webkit-box-direction: normal;
+    -ms-flex-direction: column;
+    flex-direction: column;
+  }
+}
+
+@media screen and (max-width: 840px) {
+  body[devsite-book-nav--open] {
+    overflow: hidden;
+  }
+}
+
+h1,h2,h3,h4,h5,h6 {
+  overflow: hidden;
+  padding: 0;
+  text-overflow: ellipsis;
+}
+
+h1 {
+  color: #80868b;
+  font: 300 34px/40px Roboto,sans-serif;
+  letter-spacing: -0.01em;
+  margin: 40px 0 20px;
+}
+
+[layout=docs] h2 {
+  border-bottom: 1px solid #e8eaed;
+  padding-bottom: 3px;
+}
+
+h2 {
+  font: 300 24px/32px Roboto,sans-serif;
+  letter-spacing: -0.01em;
+  margin: 40px 0 20px;
+}
+
+h3 {
+  font: 400 20px/32px Roboto,sans-serif;
+  margin: 32px 0 16px;
+}
+
+h4,h5,h6 {
+  margin: 32px 0 16px;
+}
+
+h4 {
+  font: 500 16px/24px Roboto,sans-serif;
+}
+
+h5 {
+  font: 700 14px/24px Roboto,sans-serif;
+}
+
+h6 {
+  font: 500 14px/24px Roboto,sans-serif;
+}
+
+h1+h1,h1+h2,h1+h3,h1+h4,h1+h5,h1+h6,h2+h1,h2+h2,h2+h3,h2+h4,h2+h5,h2+h6,h3+h1,h3+h2,h3+h3,h3+h4,h3+h5,h3+h6,h4+h1,h4+h2,h4+h3,h4+h4,h4+h5,h4+h6,h5+h1,h5+h2,h5+h3,h5+h4,h5+h5,h5+h6,h6+h1,h6+h2,h6+h3,h6+h4,h6+h5,h6+h6 {
+  margin-top: 0;
+}
+
+@media screen and (max-width: 600px) {
+  h1 {
+    font: 300 24px/32px Roboto,sans-serif;
+  }
+}
+
+[scrollbars]::-webkit-scrollbar {
+  height: 8px;
+  width: 8px;
+}
+
+[scrollbars]::-webkit-scrollbar-thumb {
+  background: rgba(128,134,139,.26);
+  border-radius: 8px;
+}
+
+[no-horizontal-scrollbars]::-webkit-scrollbar {
+  height: 0;
+  width: 0;
+}
+
+[scrollbars]::-webkit-scrollbar-corner {
+  background: 0;
+}
+
+[background] h2 {
+  color: #fff;
+}
+
+@media print {
+  body,  html,  :link,  :visited,  h1,  h2,  h3,  h4,  h5,  h6 {
+    color: #000 !important;
+    padding-left: 0 !important;
+    padding-right: 0 !important;
+  }
+
+  :link,  :visited {
+    text-decoration: underline;
+  }
+}
+
+@page {
+  margin: .75in;
+}

clang-tools-extra/clang-doc/tool/CMakeLists.txt

 include_directories(${CMAKE_CURRENT_SOURCE_DIR}/..)
 
 add_clang_tool(clang-doc
   ClangDocMain.cpp
   )
 
 target_link_libraries(clang-doc
   PRIVATE
   clangAST
   clangASTMatchers
   clangBasic
   clangFrontend
   clangDoc
   clangTooling
   clangToolingCore
   )
+
+install(FILES ../stylesheets/clang-doc-default-stylesheet.css
+  DESTINATION share/clang
+  COMPONENT clang-doc)
 
 

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

std::string getFormatString() {
   case OutputFormatTy::md:
     return "md";
   case OutputFormatTy::html:
     return "html";
   }
   llvm_unreachable("Unknown OutputFormatTy");
 }
 
+// This function isn't referenced outside its translation unit, but it
+// can't use the "static" keyword because its address is used for
+// GetMainExecutable (since some platforms don't support taking the
+// address of main, and some platforms can't implement GetMainExecutable
+// without being given the address of a function in the main executable).
+std::string GetExecutablePath(const char *Argv0, void *MainAddr) {
+  return llvm::sys::fs::getMainExecutable(Argv0, MainAddr);
+}
+
 bool CreateDirectory(const Twine &DirName, bool ClearDirectory = false) {
   std::error_code OK;
   llvm::SmallString<128> DocsRootPath;
   if (ClearDirectory) {
     std::error_code RemoveStatus = llvm::sys::fs::remove_directories(DirName);
     if (RemoveStatus != OK) {
       llvm::errs() << "Unable to remove existing documentation directory for "
                    << DirName << ".\n";

 // class C {};
 //
 // }
 // }
 llvm::Expected<llvm::SmallString<128>> getInfoOutputFile(StringRef Root,
                                                          StringRef RelativePath,
                                                          StringRef Name,
                                                          StringRef Ext) {
-  std::error_code OK;
   llvm::SmallString<128> Path;
   llvm::sys::path::native(Root, Path);
   llvm::sys::path::append(Path, RelativePath);
   if (CreateDirectory(Path))
     return llvm::make_error<llvm::StringError>("Unable to create directory.\n",
                                                llvm::inconvertibleErrorCode());
   llvm::sys::path::append(Path, Name + Ext);
   return Path;
int main(int argc, const char **argv) {
   if (!DoxygenOnly)
     ArgAdjuster = combineAdjusters(
         getInsertArgumentAdjuster("-fparse-all-comments",
                                   tooling::ArgumentInsertPosition::END),
         ArgAdjuster);
 
   // Mapping phase
   llvm::outs() << "Mapping decls...\n";
+  void *MainAddr = (void *)(intptr_t)GetExecutablePath;
+  std::string ClangDocPath = GetExecutablePath(argv[0], MainAddr);
   clang::doc::ClangDocContext CDCtx = {Exec->get()->getExecutionContext(),
-                                       PublicOnly};
+                                       PublicOnly, OutDirectory, ClangDocPath};
   auto Err =
       Exec->get()->execute(doc::newMapperActionFactory(CDCtx), ArgAdjuster);
   if (Err) {
     llvm::errs() << toString(std::move(Err)) << "\n";
     return 1;
   }
 
   // Collect values into output by key.
if (FileErr != OK) {
       llvm::errs() << "Error opening info file: " << FileErr.message() << "\n";
       continue;
     }
 
     if (auto Err = G->get()->generateDocForInfo(I, InfoOS))
       llvm::errs() << toString(std::move(Err)) << "\n";
   }
 
+  if (!G->get()->createResources(CDCtx))
+    return 1;
+
   return 0;
 }

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

TEST(HTMLGeneratorTest, emitNamespaceHTML) {
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
   auto Err = G->generateDocForInfo(&I, Actual);
   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"/>
 <div>
   <h1>namespace Namespace</h1>
   <h2>Namespaces</h2>
   <ul>
     <li>ChildNamespace</li>
   </ul>
   <h2>Records</h2>
   <ul>
TEST(HTMLGeneratorTest, emitRecordHTML) {
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
   auto Err = G->generateDocForInfo(&I, Actual);
   assert(!Err);
   std::string Expected = R"raw(<!DOCTYPE html>
 <meta charset="utf-8"/>
 <title>class r</title>
+<link rel="stylesheet" href="../../../clang-doc-default-stylesheet.css"/>
 <div>
   <h1>class r</h1>
   <p>
     Defined at line 10 of test.cpp
   </p>
   <p>
     Inherits from 
     <a href="../../../path/to/F.html">F</a>
TEST(HTMLGeneratorTest, emitFunctionHTML) {
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
   auto Err = G->generateDocForInfo(&I, Actual);
   assert(!Err);
   std::string Expected = R"raw(<!DOCTYPE html>
 <meta charset="utf-8"/>
 <title></title>
+<link rel="stylesheet" href="clang-doc-default-stylesheet.css"/>
 <div>
   <h3>f</h3>
   <p>
     <a href="path/to/float.html">float</a>
      f(
     <a href="path/to/int.html">int</a>
      P)
   </p>
TEST(HTMLGeneratorTest, emitEnumHTML) {
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
   auto Err = G->generateDocForInfo(&I, Actual);
   assert(!Err);
   std::string Expected = R"raw(<!DOCTYPE html>
 <meta charset="utf-8"/>
 <title></title>
+<link rel="stylesheet" href="clang-doc-default-stylesheet.css"/>
 <div>
   <h3>enum class e</h3>
   <ul>
     <li>X</li>
   </ul>
   <p>
     Defined at line 10 of test.cpp
   </p>
TEST(HTMLGeneratorTest, emitCommentHTML) {
   assert(G);
   std::string Buffer;
   llvm::raw_string_ostream Actual(Buffer);
   auto Err = G->generateDocForInfo(&I, Actual);
   assert(!Err);
   std::string Expected = R"raw(<!DOCTYPE html>
 <meta charset="utf-8"/>
 <title></title>
+<link rel="stylesheet" href="clang-doc-default-stylesheet.css"/>
 <div>
   <h3>f</h3>
   <p>
     void f(int I, int J)
   </p>
   <p>
     Defined at line 10 of test.cpp
   </p>