proposal: type-safe docs (DO NOT MERGE)

[fhur]

Introduction

The goal of this proposal is to introduce a mechanism for defining type-safe code examples.

Problem

Our code examples are not type safe. This means we can easily make typing errors. It also means that when we change the API we need to manually check the docs to see if something broke.

Goals

The goal of this proposal/MR is to have the peace of mind that when we release a new version of kysely, all code examples will compile and produce expected values.

The proposal: high level overview

1. Define code examples in typescript (see site/docs/examples/DELETE/0010-single-row.example.ts for example)
2. Import the file using the babel raw loader (see site/docs/examples/DELETE/0010-single-row.mdx, line 12)
3. Use the CodeExample component
4. Use the @docs.start-example and @docs.end-example macros to define what is actually going to be shared in the final example.

This is just a proposal, and therefore still very minimal and messy. If you think this is a good direction I will take care of cleaning everything up as well as migrating existing examples to the new type-safe format. To make this "production ready" we should also:

1. On the CI, run tsc over the ./site.
2. As the examples are actually just tests, we should also run tests on the site on the CI.
3. Clean up the example's setup script (e.g. all the Kysely instance + schema declaration)
4. Migrate all existing examples to the type-safe format.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
kysely	✅ Ready (Inspect)	Visit Preview	Jun 26, 2023 11:40am

[koskimas]

I don't know if you noticed, but the examples are automatically generated from the examples in the API documentation (source code comments) using this script.

We did it because it's way too much work to maintain two sets of examples, and we'll definitely still want to keep the API documentation.

So if we do something like this, it still needs to be automatically generated from the API documentation annotations.

I like the idea of making sure the examples work!

[fhur]

Oh nice, didn't know about that. This project moves fast 🚀 !

I guess I see a few ways in which we could move this forward:

1. Generate "type-safe examples" from unit tests: Mark some region in the unit tests as "example code". That wouldn't achieve the goal of having all examples be type-safe, but would add more examples which is always good given that we have a nice search engine.

2. Run tsc over codeblocks in the API documentation annotation: We could extract code blocks from the API documentation annotations, append the context (e.g. Kysely instance declaration), write them to a build folder and run run tsc over them. It will be dirty, but it should be doable.

What would you prefer? Or do you think the problem is less important and maybe you have something else you'd like me to focus on ?

[koskimas]

The first option would cause examples to be in two places: tests and API docs. Also: a good example doesn't necessarily make a good test and vice versa.

The second option sounds better!

[igalklebanov]

Closing due to staleness.