Bring examples into solid-docs (as individual files)

[aercolino]

Hi guys.

I was studying SolidJS and wanted to improve some examples, but then I found out that each example's files were packed into a JSON file with an array of files sources (I call it a JSON-folder file). Additionally, only the examples lived in the solid-site repo, while all the other docs did in the solid-docs repo.

So this is my small proposal for bringing all the examples from solid-site/public/examples to solid-docs/lang/en/examples-src as individual files.

Notice that all the examples are imported without any changes: I only added some code

• in solid-docs, to import examples from solid-site as real folders
• in solid-docs, to generate JSON-folder files from examples folders when building
• in solid-site, to fetch examples from solid-docs when displaying the /examples/:id route

Repos comparisons:

• solid-docs: https://github.com/solidjs/solid-docs/compare/main...aercolino:solid-docs:split-js-files?expand=1
• solid-site: https://github.com/solidjs/solid-site/compare/main...aercolino:solid-site:split-js-files?expand=1

Pieces of the puzzle:

1. solid-docs/scripts/import-examples.js
   • this script copies examples' files from the solid-site repo to the solid-docs repo, while also extracting individual files
   • run this script again to make sure the latest official examples are copied
   • this script can be deleted, eventually
   • usage: % node ./scripts/import-examples.js ../solid-site/public/examples ./langs/en/examples-src
2. solid-docs/langs/en/examples-src
   • this folder is the root of all the individual examples' files.
   • the children folders are named after the examples' ids
   • both at this level and the child folder level there are $descriptor.json files
   • it contains 47 new files
3. solid-docs/langs/en/examples-src/$descriptor.json
   • this array lists the published examples' ids, and their published order
   • we can un-publish examples just by removing them from this array
   • in fact, you will see that some children folders are not listed here
4. solid-docs/langs/en/examples-src/some-example/$descriptor. json
   • this is a POJO with name, description, and files props
   • the files props is an array of the published filenames, and their published order
   • we can un-publish examples' files just by removing them from this array
   • the category is a prefix of the example's name, like it already happens for the tutorials
5. solid-docs/langs/en/examples-src/some-example
   • this (child) folder contains everything about each example, including its source files
6. solid-docs/langs/en/examples-src/README.md
   • this mini guide for developers of the solid-docs repo describes how to create, publish, and build examples
7. solid-docs/rollup-plugins/generate-json-folders.js
   • this simple Rollup plugin packs examples folders into JSON-folders files
   • it builds from solid-docs/langs/en/examples-src to solid-docs/langs/en/examples
8. solid-docs/rollup.config.mjs
   • this Rollup configuration sets to run the generate-json-folders.js plugin
9. solid-docs/langs/en/examples
   • this folder is the root of all the generated examples
   • it contains 16 new files
10. solid-docs/src/types.ts
    • this script exports two new interfaces: SourceFile and Example
11. solid-docs/src/index.ts
    • this script exports two new functions: getExample and getExamplesDirectory
    • they only retrieve the POJOs at solid-docs/langs/en/examples/some-example.json and solid-docs/langs/en/examples/$descriptor.json respectively
12. solid-site/src/pages/Examples.data.ts
    • this script provides data for the route /examples/:id (just like before)
    • it calls the getExamplesDirectory and getExample functions, imported from solid-docs
    • notice that the examples' names keep the category, as it already happens for the tutorials
13. solid-site/src/pages/Examples.tsx
    • this script provides the page for the route /examples/:id and uses its data (just like before)