rx-player 3.26.1 → 3.26.2

package/scripts/doc-generator/create_page.js

@@ -2,30 +2,52 @@ const { promisify } = require("util");
 const cheerio = require("cheerio");
 const fs = require("fs");
 const path = require("path");
-const mkdirParent = require("./mkdir_parent.js");
-const readTitleFromMD = require("./read_title_from_md.js");
+const buildSearchIndex = require("./build_search_index.js");
 const convertMDToHTML = require("./convert_MD_to_HMTL.js");
 const constructTableOfContents = require("./construct_table_of_contents.js");
-const constructHTML = require("./construct_html.js");
+const constructHtml = require("./construct_html.js");
+const {
+  mkdirParent,
+  toUriCompatibleRelativePath,
+} = require("./utils.js");
 
 /**
  * Create and write HTML page output file from the markdown input file.
- * @param {string} inputFile - Path to the file input (a Markdown file).
- * @param {string} outputFile - Path to the resulting file output (HTML file).
- * @param {Object} [options={}]
+ * @param {Object} options
  * @returns {Promise}
  */
-module.exports = async function createDocumentationPage(
+module.exports = async function createDocumentationPage({
+  // Absolute path to the root dir where all outputed files will be
+  baseOutDir,
+  // Relative CSS URIs on this page
+  cssUris,
+  // Absolute path to the file that should be converted
   inputFile,
+  // Function translating links in Markdown files to an URL form to the right file
+  linkTranslator,
+  // HTML string for the navbar (the header on the top of the page)
+  navBarHtml,
+  // Information relative to the next documentation page, `null` if none.
+  nextPageInfo,
+  // Absolute path where the generated page should be generated.
   outputFile,
-  options = {},
-)  {
-  const { css = [],
-          linkTranslator = (link) => link,
-          getPageTitle = a => a,
-          beforeParse,
-          homeLink,
-          listLink } = options;
+  // Title of the corresponding HTML page
+  pageTitle,
+  // Information relative to the previous documentation page, `null` if none.
+  prevPageInfo,
+  // Relative JS URIs on this page
+  scriptUris,
+  // Array corresponding to the complete search index.
+  // It will be completed with data present in this file.
+  searchIndex,
+  // HTML string for the sidebar
+  sidebarHtml,
+}) {
+  const rootUrl = toUriCompatibleRelativePath(
+    path.resolve(baseOutDir),
+    path.dirname(outputFile)
+  );
+  const outputUrlFromRoot = toUriCompatibleRelativePath(outputFile, baseOutDir);
 
   const outputDir = path.dirname(outputFile);
   let data;
@@ -38,25 +60,30 @@ module.exports = async function createDocumentationPage(
     return;
   }
   const inputDir = path.dirname(inputFile);
-  const pageTitle = readTitleFromMD(data) || "Untitled Page";
+  const { content, tocMd, nbTocElements } = constructTableOfContents(data);
 
-  // remove original table of contents if one and generate new one
-  const toParse = beforeParse != null ?
-    beforeParse(data) :
-    data;
-  const { content, toc } = constructTableOfContents(toParse);
+  let contentHtml = await parseMD(content, inputDir, outputDir, linkTranslator);
+  const indexForFile = buildSearchIndex(contentHtml);
+  searchIndex.push({
+    file: outputUrlFromRoot,
+    index: indexForFile,
+  });
+  contentHtml += constructNextPreviousPage(prevPageInfo, nextPageInfo);
 
-  const domContent = await parseMD(content,
-                                   inputDir,
-                                   outputDir,
-                                   linkTranslator);
+  const tocHtml = nbTocElements > 1 ?
+    generateTocbarHtml(tocMd) :
+    "";
+  const html = constructHtml({
+    contentHtml,
+    cssUris,
+    navBarHtml,
+    rootUrl,
+    scriptUris,
+    sidebarHtml,
+    title: pageTitle,
+    tocHtml,
+  });
 
-  const html = constructHTML(getPageTitle(pageTitle),
-                             domContent,
-                             { css,
-                               toc,
-                               homeLink,
-                               listLink });
   try {
     await promisify(fs.writeFile)(outputFile, html);
   } catch (err) {
@@ -80,9 +107,45 @@ async function updateMediaTag(mediaTag, inputDir, outputDir) {
   const outDir = path.dirname(outputFile);
   const doesOutDirExists = await promisify(fs.exists)(outDir);
   if (!doesOutDirExists) {
-    await mkdirParent(outDir);
+    try {
+      await mkdirParent(outDir);
+    } catch (err) {
+      const srcMessage = (err ?? {}).message ?? "Unknown error";
+      console.error(`Error: Could not create "${outDir}" directory: ${srcMessage}`);
+      process.exit(1);
+    }
+  }
+  const doesOutFileExist = await promisify(fs.exists)(outputFile);
+  if (!doesOutFileExist) {
+    await promisify(fs.copyFile)(inputFile, outputFile);
+  }
+}
+
+function constructNextPreviousPage(prevPageInfo, nextPageInfo) {
+  if (prevPageInfo === null && nextPageInfo === null) {
+    return "";
+  }
+
+  const prevPageElt = createNextPrevElt(prevPageInfo, false);
+  const nextPageElt = createNextPrevElt(nextPageInfo, true);
+  return `<nav class="next-previous-page-wrapper" aria-label="Navigate between pages">` +
+    prevPageElt +
+    nextPageElt +
+    `</nav>`;
+
+  function createNextPrevElt(pageInfo, isNext) {
+    const base = `<div class="next-or-previous-page${isNext ? " next-page" : ""}">`;
+    if (pageInfo === null) {
+      return base + "</div>";
+    }
+    return base +
+      `<a class="next-or-previous-page-link" href="${pageInfo.link}">` +
+      `<div class="next-or-previous-page-link-label">` +
+      (isNext ? "Next" : "Previous") +
+      "</div>" +
+      `<div class="next-or-previous-page-link-name">${pageInfo.name}</div>` +
+      "</a></div>";
   }
-  await promisify(fs.copyFile)(inputFile, outputFile);
 }
 
 /**
@@ -100,13 +163,17 @@ async function updateMediaTag(mediaTag, inputDir, outputDir) {
  */
 async function parseMD(data, inputDir, outputDir, linkTranslator) {
   // TODO I don't understand Cheerio/Jquery here, that's plain ugly
-  // TODO use markdown-it plugin instead
+  // use markdown-it plugin instead?
   const $ = cheerio.load(convertMDToHTML(data));
 
   if (linkTranslator) {
     $("a").each((_, elem) => {
       const href = $(elem).attr("href");
-      if (href) {
+      if (
+        typeof href === "string" &&
+        !/^(?:[a-z]+:)/.test(href) &&
+        href[0] !== "#"
+      ) {
         $(elem).attr("href", linkTranslator(href));
       }
     });
@@ -126,3 +193,18 @@ async function parseMD(data, inputDir, outputDir, linkTranslator) {
   }
   return $.html();
 }
+
+/**
+ * Construct the table of contents part of the HTML page, containing various
+ * links to the current documentation page.
+ * @param {string} toc - Markdown for the table of contents under a list form.
+ * @returns {string} - sidebar div tag
+ */
+function generateTocbarHtml(tocMd) {
+  const tocHtml = convertMDToHTML(tocMd);
+  return "<div class=\"tocbar-wrapper\">" +
+           "<div class=\"tocbar\">" +
+             tocHtml +
+           "</div>" +
+         "</div>";
+}

package/scripts/doc-generator/generate_header_html.js

@@ -0,0 +1,148 @@
+const path = require("path");
+const { encode } = require("html-entities");
+const {
+  encodeHtmlAttributeValue,
+  toUriCompatibleRelativePath,
+  getGithubSvg,
+} = require("./utils");
+
+/**
+ * Construct HTML element, as a string, which corresponds to the header for
+ * the chosen documentation page.
+ * @param {Object} config
+ * @param {number} currentLinkIdx
+ * @param {string} currentPath
+ * @param {object} logoInfo
+ * @returns {string}
+ */
+function generateHeaderHtml(config, currentLinkIdx, currentPath, logoInfo) {
+  const { versionInfo, links, linksRightIndex } = config;
+  const hamburgerHtml = constructHamburgerMenuHtmlInHeaderBar();
+  const logoHtml = constructLogoHtmlInHeaderBar(logoInfo);
+  const currentDir = path.dirname(currentPath);
+
+  const linksHtml = links.map((l, i) => {
+    const customClass =
+      i === linksRightIndex     ? " first-right" :
+      i === linksRightIndex - 1 ? " last-left"   :
+                                         "";
+    switch (l.type) {
+      case "local-doc": {
+        const relativeUri = toUriCompatibleRelativePath(l.firstPage, currentDir);
+        const activeClass = i === currentLinkIdx ? " navbar-active" : "";
+        const cleanedHref = encodeHtmlAttributeValue(relativeUri);
+        return `<a class="navbar-item${activeClass}${customClass} hideable"` +
+          `href="${cleanedHref}">${encode(l.displayName)}</a>`;
+      }
+      case "external-link": {
+        const cleanedHref = encodeHtmlAttributeValue(l.link);
+        return `<a class="navbar-item${customClass} hideable"` +
+          `href="${cleanedHref}">${encode(l.displayName)}</a>`;
+      }
+      case "github-link":
+        return constructGithubLinkHtmlInHeaderBar(l.link, customClass);
+      case "search":
+        return constructSearchHtmlInHeaderBar(customClass);
+      case "version":
+        return constructVersionLinkHtmlInHeaderBar(versionInfo, customClass);
+    }
+  }).join("\n");
+  return `<nav class="navbar-parent">` +
+    `<div class="navbar-wrapper">` +
+    `<div class="navbar-items">` +
+    hamburgerHtml +
+    logoHtml +
+    linksHtml +
+    "</div></div> </nav>";
+}
+
+function constructHamburgerMenuHtmlInHeaderBar() {
+  return `<button aria-label="Open website index" class="hamburger-opener">` +
+    `<svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true">` +
+    `<path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" ` +
+    `stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg>` +
+    "</button>";
+}
+
+/**
+ * Returns the HTML string corresponding to the current version number, if
+ * available, and with the corresponding link, also if available.
+ * @param {Object} versionInfo
+ * @param {string} customClass
+ * @returns {string}
+ */
+function constructVersionLinkHtmlInHeaderBar(versionInfo, customClass) {
+  if (
+    versionInfo === undefined || versionInfo === null ||
+    typeof versionInfo.version !== "string"
+  ) {
+    return "";
+  }
+  let element = "";
+  let hasLink = false;
+  const { version } = versionInfo;
+  if (typeof versionInfo.link === "string") {
+    hasLink = true;
+    element += `<a class="navbar-item${customClass}"` +
+      `href="${encodeHtmlAttributeValue(versionInfo.link)}">`;
+  } else {
+    element += `<span class="navbar-item${customClass}">`;
+  }
+  element += `<span class="version-item">version: ${encode(version)}</span>`;
+  element += hasLink ? "</a>" : "</span>";
+  return element;
+}
+
+/**
+ * Returns the HTML string corresponding to the link to the github repository,
+ * through a SVG representing Github's logo.
+ * @param {string} githubLnk
+ * @param {string} customClass
+ * @returns {string}
+ */
+function constructGithubLinkHtmlInHeaderBar(githubLnk, customClass) {
+  const cleanedHref = encodeHtmlAttributeValue(githubLnk);
+  return `<a aria-label="Link to repository" class="navbar-item${customClass} hideable" href="${cleanedHref}">` +
+    getGithubSvg() +
+    "</a>";
+}
+
+function constructSearchHtmlInHeaderBar(customClass) {
+  return `<span class="navbar-item search-icon${customClass}">` +
+    `<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" ` +
+    `viewBox="0 0 20 20">` +
+    `<title>search</title>` +
+    `<path d="M19 17l-5.15-5.15a7 7 0 1 0-2 2L17 19zM3.5 8A4.5 4.5 ` +
+    `0 1 1 8 12.5 4.5 4.5 0 0 1 3.5 8z"/>` +
+    `<script xmlns=""/></svg>` +
+    `</span>`;
+}
+
+/**
+ * Returns the HTML string corresponding to the logo of the current project, if
+ * available, and with the corresponding link, also if available.
+ * @param {Object|undefined} logoInfo
+ * @returns {string}
+ */
+function constructLogoHtmlInHeaderBar(logoInfo) {
+  if (logoInfo === null || logoInfo === undefined) {
+    return "";
+  }
+
+  let logoHtml = "";
+  let hasLink = false;
+  if (typeof logoInfo.link === "string") {
+    hasLink = true;
+    logoHtml += `<a href="${encodeHtmlAttributeValue(logoInfo.link)}">`;
+  }
+  if (typeof logoInfo.url === "string") {
+    logoHtml += `<img alt="Logo" class="navbar-item navbar-item-logo"` +
+      ` src="${encodeHtmlAttributeValue(logoInfo.url)}" />`;
+  }
+  if (hasLink) {
+    logoHtml += "</a>";
+  }
+  return logoHtml;
+}
+
+module.exports = generateHeaderHtml;

package/scripts/doc-generator/generate_page_html.js

@@ -0,0 +1,116 @@
+const { encode } = require("html-entities");
+const { encodeHtmlAttributeValue } = require("./utils");
+
+/**
+ * Generate HTML page for the given documentation.
+ * @param {Object} args
+ * @param {string} args.contentHtml - HTML content for the content of the
+ * @param {Array.<string>} args.cssUrls - URLs to the CSS files that should
+ * be imported.
+ * @param {string|null|undefined} [args.faviconUrl] - Eventual URL to the
+ * favicon.
+ * `null` or `undefined` if unset.
+ * @param {string} options.navBarHtml - HTML strinng for the Navbar (the
+ * header).
+ * @param {string} options.pageListHtml - HTML string for the complete list of
+ * documentation pages with links.
+ * @param {string} options.rootUrl - Relative URL for the root of the site.
+ * This value is included in a custom script so it can be accessed from other
+ * JavaScript files.
+ * @param {Array.<string>} args.scriptUrls - URLs to the JS files that should
+ * be imported.
+ * @param {string} options.sidebarHtml - HTML string for the Sidebar.
+ * @param {string} args.title - title of the page.
+ * @param {string} options.tocHtml - HTML string for the Table of content.
+ * `undefined` if your page has no table of contents.
+ * @returns {string} - Whole HTML string for the documentation page.
+ */
+function generatePageHtml(
+  {
+    contentHtml,
+    cssUrls,
+    faviconUrl,
+    navBarHtml,
+    pageListHtml,
+    rootUrl,
+    scriptUrls,
+    sidebarHtml,
+    title,
+    tocHtml,
+  }
+) {
+  const styles = constructStylesHtml(cssUrls);
+  const scripts = constructScriptsHtml(scriptUrls);
+  const faviconHtml = typeof faviconUrl === "string" ?
+    `<link rel="icon" type="image/png" href="${encodeHtmlAttributeValue(faviconUrl)}">` :
+    "";
+  const hamburgerHtml = constructHamburgerBarHtml(pageListHtml);
+
+  return "<!DOCTYPE html><html lang=\"en\"><head>" +
+           "<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">" +
+           "<meta charset=\"utf-8\">" +
+           styles +
+           "<title>" + encode(title) + "</title>" +
+           faviconHtml +
+         "</head>" +
+         "<body class=\"no-js\">" +
+         `<script type="text/javascript">` +
+         `document.body.className = "";` +
+         `window.rootUrl = "${rootUrl}";` +
+         "</script>" +
+           "<div class=\"page-wrapper\">" +
+             navBarHtml +
+             sidebarHtml +
+             "<div class=\"content-wrapper\">" +
+               "<div class=\"content\">" +
+                 `<div id="search-wrapper">` +
+                   `<input type="search" name="search" id="searchbar" ` +
+                   `placeholder="Search in this documentation" class="active" />` +
+                   `<div id="search-results"></div>` +
+                 `</div>` +
+                 contentHtml +
+               `</div>` +
+               tocHtml +
+             "</div>" +
+           "</div>" +
+           hamburgerHtml +
+           scripts +
+           "</body></html>";
+};
+
+function constructHamburgerBarHtml(pageListHtml) {
+  return `<div class="hamburger-bar">` +
+    `<div class="hamburger-header">` +
+    `<span class="hamburger-title">Page List</span>` +
+    `<button aria-label="Close website index" type="button" class="hamburger-bar-closer">` +
+    `<svg viewBox="0 0 15 15" width="21" height="21">` +
+    `<g stroke="black" stroke-width="1.2"><path d="M.75.75l13.5 13.5M14.25.75L.75 14.25"></path></g>` +
+    `</svg></button>` +
+    `</div>` +
+    pageListHtml +
+    "</div>";
+}
+
+/**
+ * Returns links to CSS file as an HTML string to be included in the page.
+ * @param {Array.<string>} cssUrls - URL to CSS files
+ * @returns {string}
+ */
+function constructStylesHtml(cssUrls) {
+  return cssUrls.map(cssUrl =>
+    `<link rel="stylesheet" href="${encodeHtmlAttributeValue(cssUrl)}"/>`)
+    .join("");
+}
+
+/**
+ * @param {Array.<string>} scriptUrls - URL to scripts files
+ * @returns {string}
+ */
+function constructScriptsHtml(scriptUrls) {
+  return scriptUrls.map(scriptUrl =>
+    `<script type="text/javascript" src="${encodeHtmlAttributeValue(scriptUrl)}" ` +
+    `charset="utf-8"></script>`
+  ).join("");
+}
+
+module.exports = generatePageHtml;

package/scripts/doc-generator/generate_page_list_html.js

@@ -0,0 +1,93 @@
+const { encode } = require("html-entities");
+const path = require("path");
+const {
+  encodeHtmlAttributeValue,
+  getGithubSvg,
+  toUriCompatibleRelativePath,
+} = require("./utils");
+
+/**
+ * Construct exhaustive list of documentation links as an HTML string.
+ * @param {Array.<Object>} links
+ * @param {number} currentLinkIdx
+ * @param {Array.<number>} currentPageIndexes
+ * @param {string} currentPath
+ * @returns {string}
+ */
+function generatePageListHtml(
+  links,
+  currentLinkIdx,
+  currentPageIndexes,
+  currentPath
+) {
+  const currentDir = path.dirname(currentPath);
+  const linksHtml = links.map((l, linkIdx) => {
+    switch (l.type) {
+      case "local-doc": {
+        const isActiveCat = linkIdx === currentLinkIdx;
+        const catActiveClasses = isActiveCat ? " opened active" : "";
+
+        const catHtml = `<li class="page-list-item">` +
+          `<div class="page-list-group${catActiveClasses}">` +
+          encode(l.displayName) +
+          `</div><ul class="page-list-cat-group">`;
+
+        return catHtml + l.pages.map((currentPage, pageidx) => {
+          const isPageActive = isActiveCat && pageidx === currentPageIndexes[0];
+          const { displayName, outputFile } = currentPage;
+          if (!currentPage.isPageGroup) {
+            const pageActiveClasses = isPageActive ? " active" : "";
+            const relativeUri = toUriCompatibleRelativePath(outputFile, currentDir);
+            return `<li class="page-list-item${pageActiveClasses}">` +
+              `<a href="${encodeHtmlAttributeValue(relativeUri)}">` +
+              encode(displayName) +
+              `</a></li>`;
+          }
+          const pageActiveClasses = isPageActive ? " opened active" : "";
+          const pageGroupHtml = `<li>` +
+            `<div class="page-list-item page-list-group${pageActiveClasses}">` +
+            encode(displayName) +
+            `</div><ul class="page-list-group-group">`;
+          return pageGroupHtml + currentPage.pages.map((currentSubPage, spIdx) => {
+            const spActiveClasses = isPageActive && spIdx === currentPageIndexes[1] ?
+              " active" : "";
+            const { displayName, outputFile } = currentSubPage;
+            const relativeUri = toUriCompatibleRelativePath(outputFile, currentDir);
+            return `<li class="page-list-item${spActiveClasses}">` +
+              `<a href="${encodeHtmlAttributeValue(relativeUri)}">` +
+              encode(displayName) +
+              `</a></li>`;
+          }).join("\n") + "</ul></li>";
+        }).join("\n") + "</ul></li>";
+      }
+
+      case "external-link": {
+        const cleanedHref = encodeHtmlAttributeValue(l.link);
+        return `<li class="page-list-item">` +
+          `<a href="${cleanedHref}">` +
+          encode(l.displayName) +
+          "</a></li>";
+      }
+
+      case "github-link":
+        const cleanedHref = encodeHtmlAttributeValue(l.link);
+        return `<li class="page-list-item">` +
+          `<a aria-label="Link to repository" href="${cleanedHref}">` +
+            getGithubSvg() +
+            "</a></li>";
+
+      case "search":
+        return "";
+
+      case "version":
+        // TODO?
+        return "";
+    }
+  }).join("\n");
+
+  return `<ul class="page-list-wrapper">` +
+    linksHtml +
+    "</ul>";
+};
+
+module.exports = generatePageListHtml;

package/scripts/doc-generator/generate_sidebar_html.js

@@ -0,0 +1,88 @@
+const path = require("path");
+const { encode } = require("html-entities");
+const {
+  encodeHtmlAttributeValue,
+  toUriCompatibleRelativePath,
+} = require("./utils");
+
+/**
+ * Construct HTML element, as a string, which corresponds to the sidebar for
+ * the chosen documentation page.
+ * @param {Array.<Object>} pages
+ * @param {Array.<number>} currentPageIndexes
+ * @param {string} currentPath
+ * @param {Object} logoInfo
+ * @returns {string}
+ */
+function generateSidebarHtml(
+  pages,
+  currentPageIndexes,
+  currentPath,
+  logoInfo
+) {
+  const sidebarHeaderHtml = constructSidebarHeaderHtml(logoInfo);
+  const links = pages.map((p, i) => {
+    const isActive = i === currentPageIndexes[0];
+    if (!p.isPageGroup) {
+      return generateLiForPage(p, isActive);
+    } else {
+      const lis = p.pages.map((sp, j) => {
+        const isActiveSubPage = isActive && j === currentPageIndexes[1];
+        return generateLiForPage(sp, isActiveSubPage);
+      }).join("");
+      return `<li class="sidebar-item">` +
+        `<div class="sidebar-item sidebar-item-group${isActive ? " active opened" : ""}">` +
+        encode(p.displayName) +
+        "</div>" +
+        `<ul>${lis}</ul>` +
+        "</li>";
+
+    }
+  }).join("");
+  return `<aside class="sidebar-parent">` +
+    sidebarHeaderHtml +
+    `<div class="sidebar-wrapper">` +
+    `<div class="sidebar-items">${links}</div>` +
+    "</div>" +
+    "</aside>";
+
+  function generateLiForPage(p, isActive) {
+    const relativeUri = toUriCompatibleRelativePath(
+      p.outputFile,
+      path.dirname(currentPath)
+    );
+    const activeClass = isActive ? " active" : "";
+    const cleanedHref = encodeHtmlAttributeValue(relativeUri);
+    return "<li class=\"sidebar-item\">" +
+      `<a class="sidebar-link${activeClass}" href="` +
+      cleanedHref +
+      `">${encode(p.displayName)}</a>` +
+      "</li>";
+  }
+}
+
+/**
+ * @param {Object} logoInfo
+ * @returns {string}
+ */
+function constructSidebarHeaderHtml(logoInfo) {
+  let sidebarHeaderHtml = `<div class="sidebar-header">`;
+  if (logoInfo !== undefined) {
+    let hasLink = false;
+    if (typeof logoInfo.link === "string") {
+      hasLink = true;
+      sidebarHeaderHtml += `<a href="${encodeHtmlAttributeValue(logoInfo.link)}">`;
+    }
+    if (typeof logoInfo.url === "string") {
+      sidebarHeaderHtml += `<img alt="logo" class="sidebar-header-logo"` +
+        ` src="${encodeHtmlAttributeValue(logoInfo.url)}" />`;
+    }
+    if (hasLink) {
+      sidebarHeaderHtml += "</a>";
+    }
+  }
+  sidebarHeaderHtml += `</div>`;
+  return sidebarHeaderHtml;
+}
+
+module.exports = generateSidebarHtml;