Import snippets from real examples

[paulobressan]

Why

We need to have trustful code snippets that can be checked if they still works. It avoids that the snippets stop working without us knowing.

What

To have code snippets that works and can be checked by CI periodically, we need to import from real project examples that can be tested and the CI can execute, so if the example is not valid anymore we can get a notification from the CI that the example needs to be updated/fixed.

How

docusaurus supports the raw-loader to load a file, but it wouldn't be enough because it would show the whole file in the code snippet box, so a custom extract region needs to be created and a convention need to be defined to extract only a piece of code in a file.

The convention:
We add a comment to start the region with an id and a comment to close the region, for example

// #region any-id

// we can add comments too
const variable = "variable"

// #endregion any-id

so in the mdx file, we load the file and use the custom extract region function

import extractRegion from "@site/src/utils/extractRegion";
import ExampleFile from "!!raw-loader!@site/FOLDER/example.js";

<CodeBlock language="javascript" title="examples.js: a description about this snippet">
  {extractRegion(ExampleFile, "any-id")}
</CodeBlock>