rx-player 3.25.2 → 3.26.3-dev.2022021400

package/scripts/doc-generator/create_documentation.js

@@ -0,0 +1,331 @@
+const { promisify } = require("util");
+const fs = require("fs");
+const path = require("path");
+const parseDocConfigs = require("./parse_doc_configs.js");
+const createDocumentationPage = require("./create_documentation_page.js");
+const generateHeaderHtml = require("./generate_header_html.js");
+const generatePageListHtml = require("./generate_page_list_html.js");
+const generateSidebarHtml = require("./generate_sidebar_html.js");
+const {
+  mkdirParent,
+  toUriCompatibleRelativePath,
+} = require("./utils.js");
+
+async function createDirIfDoesntExist(dir) {
+  const doesCSSOutDirExists = await promisify(fs.exists)(dir);
+  if (!doesCSSOutDirExists) {
+    try {
+      await mkdirParent(dir);
+    } catch (err) {
+      const srcMessage = (err ?? {}).message ?? "Unknown error";
+      console.error(`Error: Could not create "${dir}" directory: ${srcMessage}`);
+      process.exit(1);
+    }
+  }
+}
+
+/**
+ * Create documentation for the directory given into the ouput directory given.
+ * @param {string} baseInDir
+ * @param {string} baseOutDir
+ * @param {Object} [options={}]
+ * @param {Function} [options.getPageTitle] - Callback returning the name of the
+ * page, based on the name of a single markdown document.
+ * If not set, the page title will just be the corresponding markdown's title.
+ * @param {Array.<string>} [options.css] - Optional CSS files which will be
+ * linked to each generated page.
+ * Should be the path to each of those.
+ * @param {string|undefined} [options.version] - String indicating the current
+ * version of the documented application.
+ * @returns {Promise} - Resolve when done
+ */
+async function createDocumentation(
+  baseInDir,
+  baseOutDir,
+  options = {},
+) {
+  const { css } = options;
+
+  // Copy CSS files
+  const cssOutputDir = path.join(path.resolve(baseOutDir), "styles");
+  const cssOutputPaths = css.map(cssFilepath => {
+    return path.join(cssOutputDir, path.basename(cssFilepath));
+  });
+
+  if (css.length > 0) {
+    await createDirIfDoesntExist(cssOutputDir);
+    await Promise.all(css.map(async (cssInput, i) => {
+      await promisify(fs.copyFile)(cssInput, cssOutputPaths[i]);
+    }));
+  }
+
+  // Copy JavaScript file
+  const scriptOutputDir = path.join(path.resolve(baseOutDir), "scripts");
+  const scripts = [
+    path.join(__dirname, "scripts/lunr.js"),
+    path.join(__dirname, "scripts/script.js"),
+  ];
+  const scriptOutputPaths = scripts.map(s =>
+    path.join(scriptOutputDir, path.basename(s)));
+
+  await createDirIfDoesntExist(scriptOutputDir);
+  await Promise.all(scripts.map(async (s, i) => {
+    await promisify(fs.copyFile)(s, scriptOutputPaths[i]);
+  }));
+
+  // Construct tree listing categories, pages, and relations between them.
+  const config = await parseDocConfigs(baseInDir, baseOutDir, options.version);
+
+  if (config.favicon !== undefined && typeof config.favicon.srcPath === "string") {
+    await copyFileToOutputDir(config.favicon.srcPath, baseInDir, baseOutDir);
+  }
+  if (config.logo !== undefined && typeof config.logo.srcPath === "string") {
+    await copyFileToOutputDir(config.logo.srcPath, baseInDir, baseOutDir);
+  }
+
+
+  // Construct a dictionary of markdown files to the corresponding output file.
+  // This can be useful to redirect links to other converted markdowns.
+  const fileDict = config.links.reduce((acc, linkInfo) => {
+    if (linkInfo.type !== "local-doc") {
+      return acc;
+    }
+    return linkInfo.pages.reduce((acc2, pageInfo) => {
+      if (pageInfo.isPageGroup) {
+        return pageInfo.pages.reduce((acc3, subPageInfo) => {
+          acc3[subPageInfo.inputFile] = subPageInfo.outputFile;
+          return acc3;
+        }, acc2);
+      } else {
+        acc2[pageInfo.inputFile] = pageInfo.outputFile;
+      }
+      return acc2;
+    }, acc);
+  }, {});
+
+  const searchIndex = [];
+
+  // Create documentation pages
+  for (let linkIdx = 0; linkIdx < config.links.length; linkIdx++) {
+    const currentLink = config.links[linkIdx];
+    if (currentLink.type !== "local-doc") {
+      continue;
+    }
+    for (let pageIdx = 0; pageIdx < currentLink.pages.length; pageIdx++) {
+      const currentPage = currentLink.pages[pageIdx];
+      if (!currentPage.isPageGroup) {
+        const { inputFile, outputFile } = currentPage;
+        await prepareAndCreateDocumentationPage({
+          baseOutDir,
+          config,
+          cssOutputPaths,
+          fileDict,
+          inputFile,
+          linkIdx,
+          outputFile,
+          pageIdxs: [pageIdx],
+          pageTitle: options.getPageTitle === undefined ?
+            currentPage.displayName :
+            options.getPageTitle(currentPage.displayName),
+          scriptOutputPaths,
+          searchIndex,
+        });
+      } else {
+        for (
+          let subPageIdx = 0;
+          subPageIdx < currentPage.pages.length;
+          subPageIdx++
+        ) {
+          const currentSubPage = currentPage.pages[subPageIdx];
+          const { inputFile, outputFile } = currentSubPage;
+          await prepareAndCreateDocumentationPage({
+            baseOutDir,
+            config,
+            cssOutputPaths,
+            fileDict,
+            inputFile,
+            linkIdx,
+            outputFile,
+            pageIdxs: [pageIdx, subPageIdx],
+            pageTitle: options.getPageTitle === undefined ?
+              currentSubPage.displayName :
+              options.getPageTitle(currentSubPage.displayName),
+            scriptOutputPaths,
+            searchIndex,
+          });
+        }
+      }
+    }
+  }
+
+  try {
+    const searchIndexLoc = path.join(path.resolve(baseOutDir), "searchIndex.json");
+    await promisify(fs.writeFile)(searchIndexLoc, JSON.stringify(searchIndex));
+  } catch (err) {
+    const srcMessage = (err ?? {}).message ?? "Unknown error";
+    console.error(`Error: Could not create search index file: ${srcMessage}`);
+  }
+};
+
+async function prepareAndCreateDocumentationPage({
+  baseOutDir,
+  config,
+  cssOutputPaths,
+  fileDict,
+  inputFile,
+  linkIdx,
+  outputFile,
+  pageIdxs,
+  pageTitle,
+  scriptOutputPaths,
+  searchIndex,
+}) {
+  // Create output directory if it does not exist
+  const outDir = path.dirname(outputFile);
+  await createDirIfDoesntExist(outDir);
+
+  let logoInfo = null;
+  if (config.logo !== undefined) {
+    logoInfo = {};
+    if (config.logo !== undefined && typeof config.logo.link === "string") {
+      logoInfo.link = config.logo.link;
+    }
+    if (config.logo !== undefined && typeof config.logo.srcPath === "string") {
+      const fullPath =  path.join(baseOutDir, config.logo.srcPath);
+      logoInfo.url = toUriCompatibleRelativePath(fullPath, outDir);
+    }
+  }
+  let faviconUrl = null;
+  if (config.favicon !== undefined && typeof config.favicon.srcPath === "string") {
+    const fullPath =  path.join(baseOutDir, config.favicon.srcPath);
+    faviconUrl = toUriCompatibleRelativePath(fullPath, outDir);
+  }
+  const pageListHtml = generatePageListHtml(config.links, linkIdx, pageIdxs, outputFile);
+  const navBarHtml = generateHeaderHtml(config, linkIdx, outputFile, logoInfo);
+  const pages = config.links[linkIdx].pages;
+  const sidebarHtml = generateSidebarHtml(pages, pageIdxs, outputFile, logoInfo);
+
+  let prevPageConfig = null;
+  let nextPageConfig = null;
+  if (pageIdxs.length > 1 && pageIdxs[1] > 0) {
+    prevPageConfig = pages[pageIdxs[0]].pages[pageIdxs[1] - 1];
+  } else if (pageIdxs[0] > 0) {
+    prevPageConfig = pages[pageIdxs[0] - 1];
+  }
+  if (pageIdxs.length > 1 && pageIdxs[1] < pages[pageIdxs[0]].pages.length - 1) {
+    nextPageConfig = pages[pageIdxs[0]].pages[pageIdxs[1] + 1];
+  } else if (pageIdxs[0] < pages.length - 1) {
+    nextPageConfig = pages[pageIdxs[0] + 1];
+  }
+  const prevPageInfo = prevPageConfig === null ?
+    null :
+    getRelativePageInfo(prevPageConfig, outputFile);
+  const nextPageInfo = nextPageConfig === null ?
+    null :
+    getRelativePageInfo(nextPageConfig, outputFile);
+
+  const cssUrls = cssOutputPaths
+    .map(cssOutput => toUriCompatibleRelativePath(cssOutput, outDir));
+  const scriptUrls = scriptOutputPaths
+    .map(s => toUriCompatibleRelativePath(s, outDir));
+
+  // add link translation to options
+  const linkTranslator = linkTranslatorFactory(inputFile, outDir, fileDict);
+  await createDocumentationPage({
+    baseOutDir,
+    cssUrls,
+    faviconUrl,
+    inputFile,
+    linkTranslator,
+    navBarHtml,
+    nextPageInfo,
+    outputFile,
+    pageListHtml,
+    pageTitle,
+    prevPageInfo,
+    scriptUrls,
+    searchIndex,
+    sidebarHtml,
+  });
+}
+
+/**
+ * Generate linkTranslator functions
+ * @param {string} inputFile
+ * @param {Object} fileDict
+ * @returns {Function}
+ */
+function linkTranslatorFactory(inputFile, outputDir, fileDict) {
+  /**
+   * Convert links to files that will be converted to the links of the
+   * corresponding converted output files.
+   * @param {string} link
+   * @returns {string|undefined}
+   */
+  return (link) => {
+    if (/^(?:[a-z]+:)/.test(link) || link[0] === "#") {
+      return
+    }
+    const extname = path.extname(link);
+    const indexOfAnchor = extname.indexOf("#");
+
+    const anchor = indexOfAnchor > 0 ?
+      extname.substring(indexOfAnchor) :
+      "";
+
+    const linkWithoutAnchor = link.substring(0, link.length - anchor.length);
+    const completeLink = path.join(path.dirname(inputFile), linkWithoutAnchor);
+    const normalizedLink = path.normalize(path.resolve(completeLink));
+
+    const translation = fileDict[normalizedLink];
+    if (translation === undefined) {
+      console.warn("WARNING: Local link not found.\n",
+                   "File:", inputFile, "\n",
+                   "Link:", link, "\n");
+    }
+    return translation !== undefined ?
+      toUriCompatibleRelativePath(translation, outputDir) + anchor :
+      // TODO do something better?
+      undefined;
+  };
+}
+
+function getRelativePageInfo(
+  pageConfig,
+  currentPath
+) {
+  const {
+    displayName: pDisplayName,
+    outputFile: pOutputFile
+  } = pageConfig.isPageGroup ?
+    pageConfig.pages[0] :
+    pageConfig;
+
+  const relativeHref = toUriCompatibleRelativePath(pOutputFile, path.dirname(currentPath));
+  return { name: pDisplayName, link: relativeHref };
+}
+
+async function copyFileToOutputDir(
+  filePathFromInputDir,
+  inputDir,
+  outputDir
+) {
+  const inputPath = path.join(inputDir, filePathFromInputDir);
+  const outputPath = path.join(outputDir, filePathFromInputDir);
+  const doesOutDirExists = await promisify(fs.exists)(path.dirname(outputPath));
+  if (!doesOutDirExists) {
+    try {
+      await mkdirParent(path.dirname(outputPath));
+    } catch (err) {
+      const srcMessage = (err ?? {}).message ?? "Unknown error";
+      console.error(`Error: Could not create "${outputPath}" directory: ${srcMessage}`);
+      process.exit(1);
+    }
+  }
+  const doesOutFileExist = await promisify(fs.exists)(outputPath);
+  if (!doesOutFileExist) {
+    await promisify(fs.copyFile)(inputPath, outputPath);
+  }
+}
+
+module.exports = createDocumentation;

package/scripts/doc-generator/create_documentation_page.js

@@ -0,0 +1,209 @@
+const { promisify } = require("util");
+const cheerio = require("cheerio");
+const fs = require("fs");
+const path = require("path");
+const getSearchDataForContent = require("./get_search_data_for_content.js");
+const convertMDToHTML = require("./convert_MD_to_HMTL.js");
+const constructTableOfContents = require("./construct_table_of_contents.js");
+const generatePageHtml = require("./generate_page_html.js");
+const {
+  mkdirParent,
+  toUriCompatibleRelativePath,
+} = require("./utils.js");
+
+/**
+ * Create and write HTML page output file from the markdown input file.
+ * @param {Object} options
+ * @returns {Promise}
+ */
+module.exports = async function createDocumentationPage({
+  // Absolute path to the root dir where all outputed files will be
+  baseOutDir,
+  // Relative CSS URLs on this page
+  cssUrls,
+  // Eventual URL to the favicon
+  faviconUrl,
+  // 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,
+  // HTML string for the complete list of documentation pages with links
+  pageListHtml,
+  // Title of the corresponding HTML page
+  pageTitle,
+  // Information relative to the previous documentation page, `null` if none.
+  prevPageInfo,
+  // Relative JS URLs on this page
+  scriptUrls,
+  // 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;
+  try {
+    data = await promisify(fs.readFile)(inputFile, "utf8");
+  } catch (err) {
+    /* eslint-disable no-console */
+    console.error("error reading file:", err);
+    /* eslint-enable no-console */
+    return;
+  }
+  const inputDir = path.dirname(inputFile);
+  const { content, tocMd, nbTocElements } = constructTableOfContents(data);
+
+  let contentHtml = await parseMD(content, inputDir, outputDir, linkTranslator);
+  const searchData = getSearchDataForContent(contentHtml);
+  searchIndex.push({
+    file: outputUrlFromRoot,
+    index: searchData,
+  });
+  contentHtml += constructNextPreviousPage(prevPageInfo, nextPageInfo);
+
+  const tocHtml = nbTocElements > 1 ?
+    constructTocBarHtml(tocMd) :
+    "";
+  const html = generatePageHtml({
+    contentHtml,
+    cssUrls,
+    faviconUrl,
+    navBarHtml,
+    pageListHtml,
+    rootUrl,
+    scriptUrls,
+    sidebarHtml,
+    title: pageTitle,
+    tocHtml,
+  });
+
+  try {
+    await promisify(fs.writeFile)(outputFile, html);
+  } catch (err) {
+    /* eslint-disable no-console */
+    console.error("error writing file:", err);
+    /* eslint-enable no-console */
+    return;
+  }
+};
+
+
+async function updateMediaTag(mediaTag, inputDir, outputDir) {
+  if (!mediaTag.attr("src")) {
+    return;
+  }
+  const inputFile = path.join(inputDir, mediaTag.attr("src"));
+  const outputFile = path.join(outputDir, mediaTag.attr("src"));
+  if (await promisify(fs.exists)(outputFile)) {
+    return;
+  }
+  const outDir = path.dirname(outputFile);
+  const doesOutDirExists = await promisify(fs.exists)(outDir);
+  if (!doesOutDirExists) {
+    try {
+      await mkdirParent(outDir);
+    } catch (err) {
+      const srcMessage = (err ?? {}).message ?? "Unknown error";
+      console.error(`Error: Could not create "${outDir}" directory: ${srcMessage}`);
+      process.exit(1);
+    }
+  }
+  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>";
+  }
+}
+
+/**
+ * Convert Markdown to HTML.
+ * @param {string} data - Markdown to convert
+ * @param {string} inputDir - Directory the Markdown file is in.
+ * Can be used to copy image/video/audio files.
+ * @param {string} outputDir - Directory the HTML file will be in.
+ * Can be used to copy image/video/audio files.
+ * @param {Function|null|undefined} linkTranslator - Allow to translate links
+ * from markdown to HTML. Is given the orginal link in the markdown and should
+ * return the converted link.
+ * If null or undefined, the links won't be converted.
+ * @returns {string}
+ */
+async function parseMD(data, inputDir, outputDir, linkTranslator) {
+  // TODO I don't understand Cheerio/Jquery here, that's plain ugly
+  // use markdown-it plugin instead?
+  const $ = cheerio.load(convertMDToHTML(data));
+
+  if (linkTranslator) {
+    $("a").each((_, elem) => {
+      const href = $(elem).attr("href");
+      if (typeof href === "string") {
+        $(elem).attr("href", linkTranslator(href));
+      }
+    });
+  }
+
+  const imgTags = $("img").toArray();
+  for (let i = 0; i < imgTags.length; i++) {
+    await updateMediaTag($(imgTags[i]), inputDir, outputDir);
+  }
+  const audioTags = $("audio").toArray();
+  for (let i = 0; i < audioTags.length; i++) {
+    await updateMediaTag($(audioTags[i]), inputDir, outputDir);
+  }
+  const videoTags = $("video").toArray();
+  for (let i = 0; i < videoTags.length; i++) {
+    await updateMediaTag($(videoTags[i]), inputDir, outputDir);
+  }
+  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 constructTocBarHtml(tocMd) {
+  const tocHtml = convertMDToHTML(tocMd);
+  return "<div class=\"tocbar-wrapper\">" +
+           "<div class=\"tocbar\">" +
+             tocHtml +
+           "</div>" +
+         "</div>";
+}