feat: sync docs (by copying them)

[dummdidumm]

Alternative to #55

Closes #20

This implements a different approach to syncing the docs. Rather than creating a toolchain that requires git sync or similar on build and keeps things transient, this approach implements a script that is invoked separately (and can be part of a github action for example) that mostly copies the documentation from the target repositories over into the omnisite, while also invoking scripts for creating the generated reference docs. Detailed steps:

1. pnpm sync-docs triggers sync script (can be invoked locally, from a github action, whatever)
2. script git clones the needed repositories (Svelte, SvelteKit etc) into a gitignored folder
3. script copies over documentation from cloned repositories
4. script runs the docs reference generation script on the cloned repositories' types and replaces placeholders from copied over documentation which reference sections from said generated docs
5. commit result into the content folder

Running the build (i.e. building the site using the committed content and the app code) can then be done separately.

Because the result is saved to disk, and syncing and building are split, we get a few advantages:

• build is massively simpler and faster: no dependencies on flaky git or other remote sources, no waiting on assembling and generating all the docs, as everything is already there
• syncing docs can be done in a separate Github action, and the resulting PR will give us a nice sanity check about what exactly changed
• getting started is easier, no need to sync first, just checkout the repo and go. This is especially helpful if you're working on the site itself, not the content
• translations will be easier: just don't invoke the sync script, instead modify the directories by hand. Keeping up to date with the source will also be easier because you can git-diff changes to docs
• more robust to future changes: If we change how the generated docs approach works, or other things related to how docs are structured in the other repositories, we don't need to backport that to old versions which we don't maintain anymore. Instead, they just become a frozen snapshot, and potentially we can even update some by hand if needed. I'm not saying we need/want to do this, just that we have this as an option available to us - something we wouldn't have if the docs were transient

At the same time, this lays the foundation for versioning; kit and svelte docs are both inside a v02/v05 directory (leading 0 to not mess up ordering once we're in double digits). Versioning is implemented in follow-up PR in #70.

[vercel]

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

Name	Status	Preview	Comments	Updated (UTC)
omnisite	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Sep 9, 2024 4:27pm

[benmccann]

I see sync-docs.ts is still doing a git clone. When would that be run and for what purpose?

[dummdidumm]

It's doing git clone when we want it to (you can choose by modifying the script, default is off). This allows us to

• run this from a github action (which doesn't have repos as siblings on some file system)
• run this for branches (allows us to do versioning through that, also see feat: docs versioning #70)

[trueadm]

I'm onboard with this approach and having thought about things – is the most scalable approach for us right now.