feat(HandlebarsGenerator): overloads partial

Author: alandefreitas

share/mrdocs/addons/generator/adoc/layouts/wrapper.adoc.hbs

@@ -3,6 +3,7 @@
 = Reference
 :mrdocs:
 {{/unless}}
+
 {{! Content generated with index.hbs }}
 {{{contents}}}
 

share/mrdocs/addons/generator/adoc/layouts/index-overload-set.adoc.hbs renamed to share/mrdocs/addons/generator/adoc/partials/symbols/overloads.adoc.hbs

@@ -1,12 +1,12 @@
 {{! A page when the symbol type is "overloads" }}
-[#{{symbol.anchor}}]
+[#{{{symbol.anchor}}}]
 ={{#unless @root.config.multipage}}={{/unless}} {{#if symbol.name}}{{>types/nested-name-specifier symbol=symbol.parent includeNamespace=true}}{{symbol.name}}{{else}}Unnamed overload set{{/if}}
 
-{{#if symbol.members.[0]}}
+{{#if symbol}}
 
-{{#if symbol.members.[0].doc.brief}}
+{{#if symbol.doc.brief}}
 
-{{{symbol.members.[0].doc.brief}}}
+{{{symbol.doc.brief}}}
 
 {{/if}}
 
@@ -20,10 +20,10 @@
 ----
 {{/each}}
   
-{{#if symbol.members.[0].doc.description}}
+{{#if symbol.doc.description}}
 =={{#unless @root.config.multipage}}={{/unless}} Description
 
-{{{symbol.members.[0].doc.description}}}
+{{{symbol.doc.description}}}
 {{/if}}
 
 {{#with (flattenUnique symbol.members "doc.exceptions" "exception") as |allExceptions|}}
@@ -41,10 +41,10 @@
 {{/if}}
 {{/with}}
 
-{{#if symbol.members.[0].doc.returns}}
+{{#if symbol.doc.returns}}
 =={{#unless @root.config.multipage}}={{/unless}} Return Value
 
-{{{symbol.members.[0].doc.returns}}}
+{{{symbol.doc.returns}}}
 
 {{/if}}
 
@@ -63,28 +63,28 @@
 {{/if}}
 {{/with}}
 
-{{#if symbol.members.[0].doc.preconditions}}
+{{#if symbol.doc.preconditions}}
 =={{#unless @root.config.multipage}}={{/unless}} Preconditions
 
-{{#each symbol.members.[0].doc.preconditions}}
+{{#each symbol.doc.preconditions}}
 {{{.}}}
 {{/each}}
 
 {{/if}}
 
-{{#if symbol.members.[0].doc.postconditions}}
+{{#if symbol.doc.postconditions}}
 =={{#unless @root.config.multipage}}={{/unless}} Postconditions
 
-{{#each symbol.members.[0].doc.postconditions}}
+{{#each symbol.doc.postconditions}}
 {{{.}}}
 {{/each}}
 
 {{/if}}
 
-{{#if symbol.members.[0].doc.see}}
+{{#if symbol.doc.see}}
 =={{#unless @root.config.multipage}}={{/unless}} See Also
 
-{{#each symbol.members.[0].doc.see}}
+{{#each symbol.doc.see}}
 {{{.}}}
 {{/each}}
 {{/if}}

share/mrdocs/addons/generator/common/partials/types/info-member.hbs

@@ -4,7 +4,7 @@
     {{#>markup/a href=(relativize url)}}{{#>markup/code}}{{>types/declarator-id . nolink=true}}{{/markup/code}}{{/markup/a}} {{>types/special-name-suffix .}}
 {{~/markup/td}}
 {{#>markup/td~}}
-    {{#if (ne kind "overload")~}}
+    {{#if (ne kind "overloads")~}}
         {{{~doc.brief}}}
     {{else~}}
         {{#each (unique (pluck (pluck members "doc") "brief"))~}}

share/mrdocs/addons/generator/common/partials/types/special-name-suffix.hbs

@@ -3,7 +3,7 @@
     the symbol is a special member (e.g., constructor,
     destructor, overload, variant member)
 }}
-{{#if (eq kind "overload")~}}
+{{#if (eq kind "overloads")~}}
     {{>types/special-name-suffix (front members)}}
 {{~else if (eq kind "function")~}}
     {{#if (eq class "constructor")}}

share/mrdocs/addons/generator/html/layouts/index-overload-set.html.hbs renamed to share/mrdocs/addons/generator/html/partials/symbols/overloads.html.hbs

@@ -41,6 +41,13 @@ escape(OutputRef& os, std::string_view str) const
     if (needsEscape)
     {
         os << "pass:[";
+        // Using passthroughs to pass content (without substitutions) can couple
+        // your content to a specific output format, such as HTML.
+        // In these cases, you should use conditional preprocessor directives
+        // to route passthrough content for different output formats based on
+        // the current backend.
+        // If we would like to couple passthrough content to an HTML format,
+        // then we'd use `HTMLEscape(os, str)` instead of `os << str`.
         os << str;
         os << "]";
     }

src/lib/Gen/adoc/AdocGenerator.cpp

@@ -148,14 +148,11 @@ relativize_fn(dom::Value to0, dom::Value from0, dom::Value options)
     }
     if (!relativePath.starts_with("../") && !relativePath.starts_with("./"))
     {
+        // relative hrefs needs to explicitly include "./" so that
+        // they are always treated as relative to the current page
         relativePath = "./" + relativePath;
     }
     relativePath += hash;
-
-    if (relativePath == "/boost.adoc")
-    {
-        relativePath = "." + relativePath;
-    }
     return relativePath;
 }
 
@@ -239,27 +236,18 @@ Builder(
     helpers::registerContainerHelpers(hbs_);
     hbs_.registerHelper("relativize", dom::makeInvocable(relativize_fn));
 
-    // load templates
-    exp = forEachFile(layoutDir(), false,
-        [&](std::string_view pathName) -> Expected<void>
-        {
-            // Get template relative path
-            std::filesystem::path relPath = pathName;
-            relPath = relPath.lexically_relative(layoutDir());
-
-            // Skip non-handlebars files
-            MRDOCS_CHECK_OR(relPath.extension() == ".hbs", {});
-
-            // Load template contents
-            MRDOCS_TRY(std::string text, files::getFileText(pathName));
-
-            // Register template
-            this->templates_.emplace(relPath.generic_string(), text);
-            return {};
-        });
-    if (!exp)
+    // Load layout templates
+    std::string indexTemplateFilename = fmt::format("index.{}.hbs", domCorpus.fileExtension);
+    std::string wrapperTemplateFilename = fmt::format("wrapper.{}.hbs", domCorpus.fileExtension);
+    for (std::string const& filename : {indexTemplateFilename, wrapperTemplateFilename})
     {
-        exp.error().Throw();
+        std::string pathName = files::appendPath(layoutDir(), filename);
+        Expected<std::string> text = files::getFileText(pathName);
+        if (!text)
+        {
+            text.error().Throw();
+        }
+        templates_.emplace(filename, text.value());
     }
 }
 
@@ -334,10 +322,7 @@ Expected<void>
 Builder::
 operator()(std::ostream& os, T const& I)
 {
-    std::string const templateFile =
-        std::derived_from<T, Info> ?
-            fmt::format("index.{}.hbs", domCorpus.fileExtension) :
-            fmt::format("index-overload-set.{}.hbs", domCorpus.fileExtension);
+    std::string const templateFile = fmt::format("index.{}.hbs", domCorpus.fileExtension);
     dom::Object ctx = createContext(I);
 
     auto& config = domCorpus->config;

src/lib/Gen/hbs/Builder.cpp

@@ -34,15 +34,19 @@ tag_invoke(
      * The `overloads` value is a temporary reference created
      * by the `Info` tag_invoke.
      */
-    v = dom::Object({
-        // KRYSTIAN FIXME: need a better way to generate IDs
-        { "id", fmt::format("{}-{}", toBase16(overloads.Parent), overloads.Name) },
-        { "kind",       "overload"},
-        { "name",       overloads.Name },
-        { "members",    dom::LazyArray(overloads.Members, domCorpus) },
-        { "namespace",  dom::LazyArray(overloads.Namespace, domCorpus) },
-        { "parent",     domCorpus->get(overloads.Parent) }
-    });
+    dom::Object res;
+    res.set("id", fmt::format("{}-{}", toBase16(overloads.Parent), overloads.Name));
+    res.set("kind", "overloads");
+    res.set("name", overloads.Name);
+    res.set("members", dom::LazyArray(overloads.Members, domCorpus));
+    res.set("namespace", dom::LazyArray(overloads.Namespace, domCorpus));
+    res.set("parent", domCorpus->get(overloads.Parent));
+    dom::Value firstM = domCorpus->get(overloads.Members.front());
+    if (firstM.isObject() && firstM.get("doc").isObject())
+    {
+        res.set("doc", firstM.get("doc"));
+    }
+    v = res;
 }
 
 } // mrdocs

src/lib/Metadata/Overloads.cpp

@@ -1,5 +1,6 @@
 = Reference
 :mrdocs:
+
 [#index]
 == Global namespace
 

test-files/golden-tests/alias-template.adoc

@@ -1,5 +1,6 @@
 = Reference
 :mrdocs:
+
 [#index]
 == Global namespace