chore: import upstream snapshot with attribution

docs/plugins/google-tagmanager/client.js

@@ -0,0 +1,19 @@
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+export default (function () {
+  if (!ExecutionEnvironment.canUseDOM) {
+    return null;
+  }
+
+  return {
+    onRouteUpdate({location}) {
+      if (location) {
+        setTimeout(() => {
+          window.dataLayer.push({
+            event: 'route-update',
+          });
+        }, 50);
+      }
+    },
+  };
+})();

docs/plugins/google-tagmanager/index.js

@@ -0,0 +1,93 @@
+const path = require('path');
+
+module.exports = function (context, options) {
+  const { siteConfig } = context;
+  const { themeConfig } = siteConfig;
+  const { gtm } = themeConfig || {};
+
+  if (!gtm) {
+    throw new Error(
+      `You need to specify 'gtm' object in 'themeConfig' with 'containerID' field in it to use google-tagmanager`,
+    );
+  }
+
+  const { containerID } = gtm;
+
+  if (!containerID) {
+    throw new Error(
+      'You specified the `gtm` object in `themeConfig` but the `containerID` field was missing. ' +
+        'Please ensure this is not a mistake.',
+    );
+  }
+
+  return {
+    name: 'google-tagmanager',
+
+    getClientModules() {
+      return [path.resolve(__dirname, './client')];
+    },
+
+    injectHtmlTags() {
+      return {
+        headTags: [
+          {
+            tagName: 'link',
+            attributes: {
+              rel: 'preconnect',
+              href: 'https://www.google-analytics.com',
+            },
+          },
+          {
+            tagName: 'link',
+            attributes: {
+              rel: 'preconnect',
+              href: 'https://www.googletagmanager.com',
+            },
+          },
+          {
+            tagName: 'link',
+            attributes: {
+              rel: 'stylesheet',
+              href: 'https://assets.rasa.com/styles/klaro.css',
+            },
+          },
+          {
+            tagName: 'script',
+            attributes: {
+              'type': 'opt-in',
+              'data-type': 'text/javascript',
+              'data-name': 'analytics',
+            },
+            innerHTML: `
+window.dataLayer = window.dataLayer || [{
+  deployContext: (window.netlifyMeta && window.netlifyMeta.CONTEXT) || 'development',
+  branchName: window.netlifyMeta && window.netlifyMeta.BRANCH,
+}];
+(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+})(window,document,'script','dataLayer','${containerID}');
+            `,
+          },
+          {
+            tagName: 'script',
+            attributes: {
+              defer: true,
+              src: 'https://assets.rasa.com/scripts/klaro_config.js'
+            }
+          },
+          {
+            tagName: 'script',
+            attributes: {
+              defer: true,
+              src: 'https://assets.rasa.com/scripts/klaro.js'
+            }
+          },
+        ],
+        preBodyTags: [],
+        postBodyTags: [],
+      };
+    },
+  };
+};

docs/plugins/included_source.js

@@ -0,0 +1,132 @@
+/**
+    This plugin gives us the ability to include source files
+    in a code-block in the docs, by using the following
+    syntax:
+
+        ```python (docs/sources/path/to/file.py)
+        ```
+
+    To make it work, you need to prefix the source file by `docs/sources/`.
+
+    It relies on `remark-source` and on a pre-build phase,
+    before docusaurus is started (or built). It allows us to support separate
+    versions of the docs (and of the program outputs).
+*/
+const path = require('path');
+const fs = require('fs-extra');
+const globby = require('globby');
+
+const { readFile, outputFile } = fs;
+
+const defaultOptions = {
+    docsDir: './docs',
+    relativeSourceDir: 'sources',
+    include: ['**.mdx', '**.md'],
+    pathPrefix: '../',
+};
+
+const _getIncludedSourceRe = (sourceDir) => `\`\`\`([a-z\-]+) \\(${sourceDir}/([^\\]\\s]+)\\)\n\`\`\``;
+
+/**
+    This function is used copy the included sources
+    requested in the docs. It parses all the docs files,
+    finds the included sources and copy them under the `sourceDir`.
+
+    Options:
+    - docsDir:             the directory containing the docs files
+    - relativeSourceDir:   the directory that will contain the included sources
+    - include:             list of patterns to look for doc files
+    - pathPrefix:          a path prefix to use for reading the sources
+*/
+async function getIncludedSources(options) {
+
+    options = { ...defaultOptions, ...options };
+    const { docsDir, include, relativeSourceDir, pathPrefix } = options;
+    const cleanedSourceDir = path.join(docsDir.replace('./', ''), relativeSourceDir);
+    const includedSourceRe = _getIncludedSourceRe(cleanedSourceDir);
+
+    // first, gather all the docs files
+    const docsFiles = await globby(include, {
+      cwd: docsDir,
+    });
+    const seen = new Set();
+    // second, read every file source
+    let sourceFiles = await Promise.all(docsFiles.map(async (source) => {
+        const data = await readFile(`${docsDir}/${source}`);
+        const sourceFiles = [];
+        let group, sourceFile, content;
+        // third, find out if there is a source to be included
+        // there can be multiple sources in the same file
+        const re = new RegExp(includedSourceRe, 'gi');
+        while ((group = re.exec(data)) !== null) {
+            sourceFile = group[2];
+            if (seen.has(sourceFile)) {
+                continue;
+            }
+            seen.add(sourceFile);
+            // fourth, read the source file
+            content = await readFile(`${pathPrefix}${sourceFile}`);
+            sourceFiles.push([sourceFile, content]);
+        }
+        return sourceFiles;
+    }));
+    sourceFiles = sourceFiles.flat().filter(pair => pair.length > 0);
+
+    // finally, write all the source files in the source directory
+    return await Promise.all(sourceFiles.map(async ([sourceFile, content]) => {
+        return await outputFile(`${docsDir}/${relativeSourceDir}/${sourceFile}`, content);
+    }));
+};
+
+
+/**
+    This function is used to ensure that all the documentation files
+    which rely on the `remark-source` plugin to load source files into
+    the docs continue to work across documentation versions. There is no way for
+    `remark-source` to know about the file structure that we have, that's
+    why we need this extra function. The workflow is:
+    1. Doc files are put in a version folder upon release of a new version;
+    2. The files, previously on the `main` branch, used to point to source files
+       contained in `docs/source/...`;
+    3. Now that they are in a versioned folder, we need to them to point to source files
+       contained in `versioned_docs/version-xxx/sources/...`. This is what this function
+       does.
+
+    Options:
+    - docsDir:                the directory containing the versionned docs files
+    - relativeSourceDir:      the directory that will contain the included sources
+    - include:                list of patterns to look for doc files
+*/
+async function updateVersionedSources(options) {
+    options = { ...defaultOptions, ...options };
+    const { docsDir, include, relativeSourceDir } = options;
+    const originalSourceDir = path.join(defaultOptions.docsDir.replace('./', ''), relativeSourceDir);
+    const newSourceDir = path.join(docsDir.replace('./', ''), relativeSourceDir);
+    const includedSourceRe = _getIncludedSourceRe(originalSourceDir);
+
+    // first, gather all the docs files
+    const docsFiles = await globby(include, {
+      cwd: docsDir,
+    });
+    const seen = new Set();
+    // second, read every doc file and compute their updated content
+    let newDocsFiles = await Promise.all(docsFiles.map(async (source) => {
+        const data = await readFile(`${docsDir}/${source}`);
+        // third, find out if there is a source to be included
+        // there can be multiple sources in the same file
+        const re = new RegExp(includedSourceRe, 'gi');
+        const updatedData = data.toString().replace(re, `\`\`\`$1 (${newSourceDir}/$2)\n\`\`\``);
+        return (updatedData != data) ? [`${docsDir}/${source}`, updatedData] : [];
+    }));
+
+    newDocsFiles = newDocsFiles.filter(pair => pair.length > 0);
+
+    // finally, update all the docs files with the path to the versioned source
+    return await Promise.all(newDocsFiles.map(async ([docsFile, updatedContent]) => {
+        return await outputFile(docsFile, updatedContent);
+    }));
+}
+
+
+module.exports = getIncludedSources;
+module.exports.updateVersionedSources = updateVersionedSources;

docs/plugins/program_output.js

@@ -0,0 +1,153 @@
+/**
+    This plugin gives us the ability to insert the output of
+    a program in a code-block in the docs, by using the following
+    syntax:
+
+        ```text [rasa --help]
+        ```
+    It is inspired by `remark-source` and also relies on a pre-build phase,
+    before docusaurus is started (or built). It allows us to support separate
+    versions of the docs (and of the program outputs).
+
+
+    Caveat: this plugin operates at 2 separate points in time:
+        1. During the "pre-build" phase, pre-generating files inside the
+           sources/ folder. This phase is run on the "main" version of the repo
+           (main branch, release branches, tags, etc...), which doesn't have
+           several versions of the docs site. This is why `getProgramOutputs()` is
+           version-agnostic and simply outputs files in `mainSourceDir`.
+        2. At the build phase, happening on the `documentation` branch. In this context,
+           there are multiple versions of the docs, and the plugins needs to support that.
+           This is why the `remarkProgramOutput()` is version-aware and takes care
+           of loading the files from a versioned path.
+*/
+const fs = require('fs');
+const globby = require('globby');
+const visitChildren = require('unist-util-visit-children');
+const { promisify } = require('util');
+
+const exec = promisify(require('child_process').exec);
+const { readFile, writeFile } = fs.promises;
+
+
+const PROGRAM_OUTPUT_RE = /```[a-z]+ \[([^\]]+)\]\n```/;
+
+const VERSIONED_DOCS_PATH_RE = /(\/versioned_docs\/version-\d+\.x)\//;
+
+const defaultOptions = {
+    docsDir: './docs',
+    sourceDirectoryName: 'sources',
+    mainSourceDir: './docs/sources',
+    include: ['**.mdx', '**.md'],
+    commandPrefix: '',
+};
+
+/**
+    This function is use to get output of programs
+    requested in the docs. It parses all the docs files,
+    generates outputs and save them as files.
+
+    Options:
+    - docsDir:              the directory containing the docs files
+    - mainSourceDir:        the directory that will contain the program outputs
+    - sourceDirectoryName:  the name (relative) of the source directory
+    - include:              list of patterns to look for doc files
+    - commandPrefix:        a prefix to be prepended before each command
+*/
+async function getProgramOutputs(options) {
+
+    options = { ...defaultOptions, ...options };
+    const { docsDir, include, mainSourceDir, commandPrefix } = options;
+    // first, gather all the docs files
+    const docsFiles = await globby(include, {
+      cwd: docsDir,
+    });
+    const seen = new Set();
+    // second, read every file source
+    let commands = await Promise.all(docsFiles.map(async (source) => {
+        const data = await readFile(`${docsDir}/${source}`);
+        const commands = [];
+        let group, command, stdout;
+        // third, find out if there is a program output to be generated
+        // there can be multiple outputs in the same file
+        const re = new RegExp(PROGRAM_OUTPUT_RE, 'gi');
+        while ((group = re.exec(data)) !== null) {
+            command = group[1];
+            if (seen.has(command)) {
+                continue;
+            }
+            seen.add(command);
+            // fourth, call the command to generate the output
+            output = await exec(`${commandPrefix} ${command}`);
+            commands.push([command, output.stdout]);
+        }
+        return commands;
+    }));
+    commands = commands.flat().filter(pair => pair.length > 0);
+
+    // finally, write all the command outputs as files in the `mainSourceDir`
+    return await Promise.all(commands.map(async ([command, output]) => {
+        return await writeFile(`${mainSourceDir}/${commandToFilename(command)}`, output);
+    }));
+};
+
+
+/**
+    Custom remark plugin to replace the following blocks:
+
+    ```text [rasa --help]
+    ```
+
+    with the actual output of the program (here `rasa --help`).
+    It relies on the output of `getProgramOutputs()` above,
+    and is inspired by `remark-sources` plugin.
+*/
+function remarkProgramOutput(options = {}) {
+    options = { ...defaultOptions, ...options };
+    return (root, { history }) => {
+        visitChildren((node, index, parent) => {
+            if (node && node.type === 'code') {
+                const content = readCommandOutput(node.meta, options, history[0]);
+                if (content !== undefined) {
+                    node.value = content;
+                }
+            }
+        })(root);
+    };
+}
+
+
+function readCommandOutput(meta, { mainSourceDir, sourceDirectoryName }, filename) {
+    if (!meta) {
+        return undefined;
+    }
+    if (meta[0] !== '[' || meta[meta.length - 1] !== ']') {
+        return undefined;
+    }
+    meta = meta.slice(1, -1);
+    const sourceFile = `${getVersionedSourceDir(mainSourceDir, sourceDirectoryName, filename)}/${commandToFilename(meta)}`
+    try {
+        return fs.readFileSync(sourceFile, { encoding: 'utf8' });
+    } catch (e) {
+        throw new Error(`Failed to read file: ${sourceFile} for meta ${meta}`);
+    }
+}
+
+
+function commandToFilename(command) {
+    return command.replace(/[^a-z0-9]/gi, '_').toLowerCase() + '.txt';
+}
+
+/**
+    By analyzing the `filename` argument, we can guess if the file we want
+    to load is in a specific version of the docs, or the main one.
+*/
+function getVersionedSourceDir(mainSourceDir, sourceDirectoryName, filename) {
+    const re = new RegExp(VERSIONED_DOCS_PATH_RE, 'gi');
+    const match = re.exec(filename);
+    return match === null ? mainSourceDir : `.${match[1]}/${sourceDirectoryName}`;
+}
+
+
+module.exports = getProgramOutputs;
+module.exports.remarkProgramOutput = remarkProgramOutput;