Integrate genType as 'TypeScript Interop' chapter into main docs

[fhammerschmidt]

ryyppy commented 2 weeks ago

A few things I'd change now that we have the chance to make structural changes to the genType docs:

0. GenType is now a builtin tool, and we should not treat this section as if it would still be a library. Maybe the Introduction should rather be something like "ReScript & TS" which would briefly mention the general concepts and philosophy, plus the setup instructions (instead of having the "Getting started" page)
1. The general sidebar structure of genType doesn't make much sense anymore (and I regretted building it this way back then). Ideally, we'd provide more concrete sidebar items that users would be looking for when interoping with TS (as we do with "JavaScript interop". The "Usage" page for instance already has a good starting point (although some items sound a little abstract), maybe it would make sense to experiment here to branch out in different documents instead.

• 

3. Same feeling for supported types as in the previous point... one could provide separate sidebar items for "Bind to TS primitive values", "Bind to TS objects", "Bind variants to TS", etc with proper examples (from/to mappings) to make it copy-pastable and easy to understand.

[cometkim]

I built the homepage and took a quick look at the outline.

This is the feedback so far.

• Mentions of runtime features should be removed. It should all be considered deprecated. (specifically genType.import, genType.as, shims)
• The statement about runtime mappers is also no longer true.
• Projects that use genType are also TypeScript projects. For better experience, the configuration guide should cover of tsconfig.json too.
• The explanation of interop behavior feels like a bit of low-level information. I suggest adding guides/practice documents from a higher-level perspective. (examples: "Dealing with conventional differences", "Bring your own pipe", "Making it more convenient in JS/TS-side", etc)

Can you update any changes you are working on? I might submit another PR to your branch.

[fhammerschmidt]

This new version of the PR is totally simplified since lot's of runtime conversion features were removed, FCMs do not work (according to @cometkim) and more things got deprecated.
In the future, we want to have some export=all feature for genType that we can use for the docs site and can then, in theory, show the generated TS types for every single example.

That way we would promote genType to the seamless experience it should be.

But for now I think this is the fastest path going forward. Let's merge this soon.