Merge pull request #10 from savetheclocktower/apd-misc

Custom data (and other tweaks)

docs/main.js

@@ -85,7 +85,8 @@ class AutoTOC {
   }
 
   bundleForTag (node, index) {
-    return { node, name: node.innerText, id: node.id, index, level: this.levelForTag(node), children: [] };
+    let name = node.dataset.name || node.innerText
+    return { node, name, id: node.id, index, level: this.levelForTag(node), children: [] };
   }
 
   levelForTag (node) {
@@ -215,15 +216,19 @@ class HeadingObserver {
 
     let sidebarRect = sidebar.getBoundingClientRect();
     let elementRect = element.getBoundingClientRect();
-    let yDistanceTop = elementRect.top - sidebarRect.top;
-    if (yDistanceTop < 0) {
+
+    // The highest and lowest visible Y positions within the viewport.
+    let topEdge = sidebarRect.top;
+    let bottomEdge = sidebarRect.top + sidebarRect.height;
+    if (elementRect.top < topEdge) {
       // The active link is above the scroll position. Nudge it in the negative
       // direction just enough to bring the link on screen.
-      sidebar.scrollTop += yDistanceTop;
-    } else if (elementRect.bottom > window.innerHeight) {
+      let diff = topEdge - elementRect.top;
+      sidebar.scrollTop -= diff;
+    } else if (elementRect.top + elementRect.height > bottomEdge) {
       // The active link is below the scroll position. Nudge it in the positive
-      // direction jsut enough to bring the link on screen.
-      let diff = elementRect.bottom - window.innerHeight;
+      // direction just enough to bring the link on screen.
+      let diff = elementRect.bottom - bottomEdge;
       sidebar.scrollTop += diff;
     }
   }

hovercard_resolution/index.js

@@ -67,13 +67,12 @@ async function resolve() {
       throw new Error(`Invalid hovercard title: ${JSON.stringify(title)}`);
     }
     let targetPath = Path.join(OUT, `${value}.json`);
-    let relativePath = Path.relative(CWD, targetPath);
-    console.log(`[hovercard] Writing ${relativePath}`);
+    // let relativePath = Path.relative(CWD, targetPath);
     FS.writeFileSync(targetPath, JSON.stringify(doc));
   }
 
   if (emptyHovercards.size > 0) {
-    console.log(`There are ${emptyHovercards.size} unresolved hovercard values!`);
+    console.warn(`There are ${emptyHovercards.size} unresolved hovercard values!`);
     for (let emptyValue of Array.from(emptyHovercards).sort()) {
       console.log(emptyValue);
     }
@@ -136,7 +135,7 @@ function buildCacheForClass (label, klass, cacheByLabel) {
     let value = `${klass.name}::${instanceMethod.name}`;
     cacheByLabel.set(value, {
       value: simplifyLabel(value),
-      title: value,
+      title: instanceMethod.customData?.name ?? value,
       description: instanceMethod.summary || (instanceMethod.returnValues?.[0]?.description ?? ""),
       link: `${baseLink}${instanceMethodAnchor(instanceMethod.name)}`
     });
@@ -146,35 +145,40 @@ function buildCacheForClass (label, klass, cacheByLabel) {
     let value = `${klass.name}::${instanceProperty.name}`;
     cacheByLabel.set(value, {
       value: simplifyLabel(value),
-      title: value,
+      title: instanceProperty.customData?.name ?? value,
       description: instanceProperty.summary ?? "",
       link: `${baseLink}${instanceMethodAnchor(instanceProperty.name)}`
     });
   }
 
   for (let classMethod of (klass.classMethods ?? [])) {
     let value = `${klass.name}.${classMethod.name}`;
-    cacheByLabel.set(value, {
+
+    let bundle = {
       value: simplifyLabel(value),
-      title: value,
+      title: classMethod.customData?.name ?? value,
       description: classMethod.summary || (classMethod.returnValues?.[0]?.description ?? ""),
       link: `${baseLink}${classMethodAnchor(classMethod.name)}`
-    });
+    };
+
+    cacheByLabel.set(value, bundle);
   }
 
   for (let classProperty of (klass.classProperties ?? [])) {
     let value = `${klass.name}::${classProperty.name}`;
     cacheByLabel.set(value, {
       value: simplifyLabel(value),
-      title: value,
+      title: classProperty.customData?.name ?? value,
       description: classProperty.summary  ?? "",
       link: `${baseLink}${classMethodAnchor(classProperty.name)}`
     });
   }
 }
 
 async function resolveApiHovercard(_simpleLabel, label, cache) {
-  return cache.get(label) ?? false;
+  let cached = cache.get(label)
+  if (!cached) return false;
+  return { ...cached };
 }
 
 let bundledPackages;

layouts/api/classMethods.ejs

@@ -1,5 +1 @@
-<% if (content.length > 0) { %>
-  <h4>Class Methods</h4>
-<% } %>
-
 <%- include("method", { separator: "." }) %>

layouts/api/method.ejs

@@ -1,8 +1,16 @@
 <% for (const item of content) { %>
-  <section class="api-entry" id="<%= anchorize(item.name) %>">
-    <h4 class="api-entry__name">
-      <a href="#<%= anchorize(item.name) %>">
-        <%= locals.separator ?? '::' %><%= item.name -%><%- include("argument_list", { item: item }).trim() -%></a>
+  <%
+    let fragment = anchorize(item.customData?.slug ?? item.name)
+    let customSignature = item.customData?.signature
+    let customName = item.customData?.name
+  %>
+  <section class="api-entry">
+    <h4 class="api-entry__name" data-name="<%= customName ?? item.name %>" id="<%= anchorize(item.name) %>">
+      <% if (item.customData?.signature) { %>
+        <a href="#<%= fragment %>"><%= item.customData.signature %></a>
+      <% } else { %>
+        <a href="#<%= fragment %>"><%= locals.separator ?? '::' %><%= item.name -%><%- include("argument_list", { item: item }).trim() -%></a>
+      <% } %>
       <a class="icon api-entry__source-link" href="<%=  item.srcUrl %>" aria-label="Source link"></a>
     </h4>
     <div class="api-entry__summary">

layouts/api/page.ejs

@@ -1,6 +1,5 @@
 <!-- Pulsar API Documentation Page -->
-<%-include("header")%>
-
+<%- include("header") %>
   <body>
     <%- include("page_header", { platform_switcher: false }) %>
     <div class="content">
@@ -18,7 +17,8 @@
       -%>
       <main class="container">
         <section class="header">
-          <h1 class="title" id="title"><%= title %></h1>
+          <% let pageTitle = (content.customData?.name ?? title) %>
+          <h1 class="title" id="title"><%= pageTitle %></h1>
         </section>
 
         <section class="description">

layouts/api/summary.ejs

@@ -1,10 +1,20 @@
 <!-- Pulsar API Documentation Summary Page -->
-<%-include("header")%>
+<%- include("header") %>
 
   <body>
     <%- include("page_header", { platform_switcher: false }) %>
     <div class="content">
-      <%-include("sidebar", { bar: sidebar, include_summary: true, indexTitle: locals.indexTitle, include_toc: true })%>
+      <%-
+        include(
+          "sidebar",
+          {
+            bar: sidebar,
+            indexTitle: locals.indexTitle,
+            include_summary: true,
+            include_toc: true
+          }
+        )
+      %>
       <main class="container">
         <section class="header">
           <h1 class="title" id="title"><%=title%></h1>

less/api.less

@@ -8,7 +8,9 @@
 }
 
 .section-name {
-  border-bottom: 2px solid var(--table-border);
+  border-bottom: 5px solid var(--thematicBreak-color);
+  padding-bottom: 0.25rem;
+  margin-bottom: 3rem;
 }
 
 .description__header {
@@ -18,9 +20,9 @@
 .api-entry {
 
   & + .api-entry {
-    padding-top: 4rem;
+    padding-top: 3rem;
     border-top: 5px solid var(--thematicBreak-color);
-    margin-top: 4rem;
+    margin-top: 3rem;
 
     .api-entry__name {
       margin-top: 0;
@@ -29,7 +31,7 @@
 
   & + .section-name {
     padding-top: 3rem;
-    margin-top: 3rem;
+    margin-top:  3rem;
   }
 
   &__source-link {

less/sidebar.less

@@ -18,7 +18,7 @@
     top: calc(var(--pageHeader_height, 0) + 1.5rem);
     bottom: 0;
     min-height: 50vh;
-    max-height: calc(100vh - var(--pageHeader_height));
+    max-height: calc(95vh - var(--pageHeader_height));
     max-width: 250px;
     min-width: 250px;
     // Margin-top matches the height of the heading plus its padding — so that
@@ -41,7 +41,6 @@
 .sidebar__contents,
 .sidebar__toc {
   padding: 0 0 1.5rem;
-  max-height: 100%;
 
   ul li {
     margin: 0;

markdown-it-plugins/hovercard.js

@@ -18,57 +18,57 @@ function replacer(state) {
   let pos;
 
   const labelStart = state.pos + 1;
-  const labelEnd = parseHovercard(state, state.pos + 1);
+  const labelEnd = parseHovercard(state, labelStart);
   if (labelEnd < 0) { return false }
 
   pos = labelEnd + 1;
   const label = state.src.slice(labelStart, labelEnd);
 
-  let normalizedLabel = label;
-  if (state.env?.type === 'api') {
-    if (label.startsWith('::')) {
-      // Disambiguate this label name by including the name of the page we're
-      // on.
-      normalizedLabel = `${state.env.name}${label}`;
-    }
-  }
-  let simpleLabel = simplifyLabel(normalizedLabel);
+  let labelData = parseHovercardLabel(label, state);
 
   state.pos = labelStart;
   state.posMax = labelEnd;
 
   let href;
-  if (STATIC_HOVERCARD_URLS.has(label)) {
-    href = STATIC_HOVERCARD_URLS.get(label);
+  if (STATIC_HOVERCARD_URLS.has(labelData.token)) {
+    href = STATIC_HOVERCARD_URLS.get(labelData.token);
   } else {
-    href = inferHrefFromHovercardText(label, state.env?.type === 'api');
+    href = inferHrefFromHovercardText(labelData.token, state.env?.type === 'api');
   }
 
   const token_o = state.push("a_open", "a", 1);
   const attrs = [
-    ["data-hovercard", simpleLabel],
-    ["data-hovercard-full", normalizedLabel],
+    ["data-hovercard", labelData.slug],
+    ["data-hovercard-full", labelData.normalized],
+    ["data-hovercard-text", labelData.text],
     ["href", href]
   ];
   token_o.attrs = attrs;
 
   state.linkLevel++;
   state.md.inline.tokenize(state);
+  if (label !== labelData.text) {
+    // This is a bit hacky; there might be a better approach. If we need to
+    // alter the link text, we do so by forcing the link text to be tokenized,
+    // then changing the token's content after the fact.
+    state.tokens[state.tokens.length - 1].content = labelData.text;
+  }
   state.linkLevel--;
 
   state.push("a_close", "a", -1);
 
   // Sometimes we need to transform hovercard syntax without any filesystem
   // side-effects.
   if (!state.env?.skip_hovercard) {
-    storeHovercard(simpleLabel, normalizedLabel);
+    storeHovercard(labelData.slug, labelData.normalized);
   }
 
   state.pos = pos;
   state.posMax = max;
   return true;
 }
 
+// Finds the ending position of a hovercard.
 function parseHovercard(state, start) {
   const max = state.posMax;
   const oldPos = state.pos;
@@ -162,3 +162,71 @@ function writeHovercardStoreToDisk () {
   let json = JSON.stringify(obj, null, 2);
   FS.writeFileSync('hovercard_list.json', json);
 }
+
+// Given the text between `{` and `}`, returns various formats of the text
+// within.
+//
+// An ordinary hovercard reference looks like `{TextEditor}`, but it's also
+// possible to use different link text in a hovercard link: `{TextEditor "the
+// text editor"}`. To use this format, you must wrap your link text in a
+// single- or double-quoted string and separate it from the token by a space.
+//
+// This method therefore returns an object with four keys. Consider the
+// following example, presumed to be part of a comment block inside
+// `src/text-editor.js`:
+//
+//    It's a good idea {::save "to save the document"} before calling
+//    this method.
+//
+// This function would return the following keys:
+//
+// * `token`: The original token (`::save` — which, if not for the presence of
+//    the explicit link text, would be used as the anchor text)
+// * `slug`: The slugified version for internal use (`texteditor__save`)
+// * `normalized`: The expanded version of the token used for symbol resolution
+//   (`TextEditor::save`)
+// * `text`: The text to be used for the anchor tag (`to save the document`)
+//
+function parseHovercardLabel (label, state) {
+  let token = label, normalized, text;
+
+  if (label.includes(' ')) {
+    let index = label.indexOf(' ');
+    token = label.substring(0, index);
+    let rawText = label.substring(index + 1);
+    // Must start with a quote character.
+    if (!(/['"]/).test(rawText.charAt(0))) {
+      console.error(label, JSON.stringify(rawText.charAt(0)), state.env)
+      throw new Error(`Illegal hovercard text!`)
+    }
+    // Must end with a quote character.
+    if (rawText.charAt(0) !== rawText.charAt(rawText.length -1)) {
+      console.error(label, state.env)
+      throw new Error(`Illegal hovercard text!`)
+    }
+    // We expect `rawText` to be a string.
+    text = JSON.parse(rawText);
+    if (typeof text !== 'string') {
+      console.error(label, state.env)
+      throw new Error(`Illegal hovercard text!`)
+    }
+  } else {
+    text = token;
+  }
+
+  normalized = token;
+
+  if (state.env?.type === 'api') {
+    if (label.startsWith('::') || label.startsWith('.')) {
+      // Disambiguate this label name by including the name of the page we're
+      // on.
+      normalized = `${state.env.name}${token}`;
+      if (text === token) {
+        text = normalized;
+      }
+    }
+  }
+
+  let result = { token, normalized, text, slug: simplifyLabel(normalized) };
+  return result;
+}

pulsar-api/src/index.js

@@ -108,9 +108,10 @@ function content2sidebar(content, version) {
 
   for (let key of keys) {
     let item = map.get(key);
+    let name = item.customData?.name ?? item.name
     sidebar.push({
-      text: item.name,
-      summary: mdRender(item.summary, { type: 'api', name: item.name, version }),
+      text: name,
+      summary: mdRender(item.summary, { type: 'api', name, version }),
       link: item.name
     });
   }