Feat/function each in separate file

[casaper]

This might look like a horrible amount of changes, but it actually is not as bad as it might look at first glance.

It's basically doing this:

• splits each function chapter into its own file in readme_src//.md
• adds a little script that wraps all of these into README.md

The intention is to have clear organisation in documentation by function and a generated TOC for these documentations.
I presume it might also help preventing mistakes like that header structure mix up I fixed with cd99895

The resulting README.md is almost the same as it is now.
This commit includes the changes rendering that does to README.md.

The intention is, to have the descriptions a bit more manageable and
avoid semantic structure mix-ups.

---

The first three commits (5e1c8a2, 6d217ea, 5e1c8a2) are actually in another PR #334 this PR is based on.

Unfortunately there is no way (none I'd know of at least) to base a forked PR to another PR, so keep the changes apart for you. Sry about that.

[nick-w-nick]

@casaper What are your thoughts on creating a configuration file that contains all of the function names and their associated examples/browser compatibility/metadata and generating the README's from that?

For example, the _.chunk function alternative:

const config = {
    array: [
        {
            name: 'chunk',
            description: 'Creates an array of elements split into groups the length of size.',
            path: 'array/chunk.js',
            args: [
                [ 'a', 'b', 'c', 'd' ],
                3
            ],
            compatibility: {
                caniuse: 'https://caniuse.com/mdn-javascript_operators_spread_spread_in_function_calls',
                chome: '46.0',
                edge: '12.0',
                firefox: '16.0',
                ie: false,
                opera: '17.0',
                safari: '8.0'
            },
            performance: {
                lodash: {
                    ops: 109395371,
                    margin: 0.66
                },
                native: {
                    ops: 213985744,
                    margin: 0.61
                }
            }
        }
    ]
};

We could easily write a script similar to the one you have already to generate each section of the README programmatically, while making it more ergonomic to edit via a configuration file rather than a set of .md files individually.

This also allows for us to add new features, like performance metrics comparison, without needing to manually edit each individual markdown file.

I'd be happy to collaborate with you on such a change, given you've already put a lot of work into the initial restructuring of the data.

[casaper]

@nick-w-nick

Hello

Perhaps to get in sync a bit easyer, I roughly map out what my intention was here

1. chunk the whole snake thing up into more manageable chunks, but produce roughly the same thing as we have
2. the generated caniuse db output for browser compatibility output I added mainly for quirking around with the thing, and to give my starter with this a little more reason of existence perhaps 😉

So I see this as a preparation step, to come with the actual new features later on (not this PR, a further following, or two):

The further picture, for like 1 or to steps after what I'm trying to start with this MR was actually to have md files per function, that pull in actual js and ts files in their code examples.

So I picture

./readme_src/010-Array/chunk/text.md
./readme_src/010-Array/chunk/example.js
./readme_src/010-Array/chunk/example.ts
./readme_src/010-Array/chunk/test.spec.ts

I imagined:

• GitHub action linting the js and ts file
• the spec prooves the thing actually works as the example claims
• the md has a syntactic sugar '```js:chunk.js' that pulls the example into the MD (allows the author to conveniently author in md)

And then the generator compiles the chunk.js and chunk.ts into the example for the author.

Another thing I thought of perhaps being good, would be some sort of loader, that loads the example to some JS playground, so the user can click "try this on CodePen" (or what ever other playground) and see how it works.

Performance

I like your idea with the performance comparisons. That'd be very sexy.

Document creator

My compiler is very simple and hand-freaked. So perhaps something like pandoc or another document generator would probably be the better and saner solution for the future.
I'm happy for any suggestions in that regard.

I just did my little script, because I knew that there is a quazillion of docs generators out there, and they are for sure a primo rabbit hole to get lost in. So just dirty hacking that little script seemed the more straight forward solution to get started with

So @nick-w-nick I'd be glad if we could colaborate on that. So please tell me what you think about my picture, and what you think you'd do differently.

To get further:

How about getting the most simple version of this here merged, and then tasks could be split up between us more easyly...

[nick-w-nick]

I agree. All of those should definitely be possible.

The only thing I think we should aim to do differently is to only interact with the .md files in one direction, AKA only generate the .md files, and reserve any content changes for the configuration file(s).

The code can be stored in the code.js / code.ts files for the native function, and the surrounding content like description, compatibility information and performance metrics can be stored in either a centralized config.js file, or we can create a config file for each function and then can utilize a main template to generate the README using the data from each config file.

I agree that we should get your changes merged though so we can preemptively already have everything split up and ready to be moved into configuration files. I'm not an approved maintainer though, so we will need to wait until someone is able to come along and review the PR formally.

[binury]

If it's any consolation that this will probably never be merged, you have my kudos for your massive refactoring undertaking