Read docs from svelte and kit repos

[benmccann]

My first attempt was to checkout the other repos as a sibling to this one. Then if you already have the svelte or kit repo checked out locally you wouldn't have to do anything and they'd automatically be used without needing to mess with symlinks or anything. However, that didn't work because it seems you can't create files outside the project root on vercel. The current approach is slightly more setup for devs if you want to use a local version of a docs repo as you need to create a symlink, but I suppose it allows for a bit more flexibility as well. I added some basic setup instructions in a new readme.

We will need to setup deploy hooks at some point to trigger deploys when the docs are updated in kit, svelte, etc. repos: https://vercel.com/docs/deployments/deploy-hooks. I filed #59 to track that

[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	Jul 12, 2024 6:55pm

[dummdidumm]

Looks good 👍 Two remaining questions though:

• how do we do docs versioning? Right now there's nothing with regards to that. We can either have them versioned within the referenced repositories (e.g. in the Svelte repo we have documentation/v4/.., documentation/v5/.. etc), or we adjust the script to checkout specific branches into specific folders inside repos
• how do we do the reference docs? Right now you left that part in for SvelteKit, and for Svelte it's removed but they still show up in the side-bar, but empty

[benmccann]

how do we do docs versioning? Right now there's nothing with regards to that. We can either have them versioned within the referenced repositories (e.g. in the Svelte repo we have documentation/v4/.., documentation/v5/.. etc), or we adjust the script to checkout specific branches into specific folders inside repos

I don't have a strong preference between those two options. Perhaps checking it out again could make more sense if you had a bug fix that needed a docs adjustment so that you can do those in a single PR, but those seem far and few between. Putting them in folders in main could be easier if you needed to adjust the docs for two versions in a single PR, which seems like it would be a lot more common. I think the tooling here would be easier as well. So I guess I lean towards that actually

Edit: though the question of generated reference docs makes it harder to check the docs into main. I guess those would pretty much have to come from the branch that contains the types unless we fetched them separately from the npm package. I suppose checking out multiple versions of the repo with different branches might end up being easier in order to support the reference docs

how do we do the reference docs? Right now you left that part in for SvelteKit, and for Svelte it's removed but they still show up in the side-bar, but empty

Ah, thanks. I hadn't noticed they were missing since they still appear in the sidebar. I added them both back for now. It looks like the generated kit docs are currently checked into this repo, but we should probably generate them here instead. I think that would work better than checking them into the kit and svelte repos so that we can keep all the generation logic located here, which will make it easier to change that logic compared to if we have to link in site-kit to kit and svelte again when working on the logic.

How do you run the sync-docs.js script? It pulls in stuff from site-kit/markdown, but site-kit exports them as .ts files, which makes it bomb out. It would seem to me like we need to build site-kit and export them as .js files, but you also mentioned above that you were trying to avoid that

[benmccann]

Once we get the reference docs generation working we can revert the changes I made to content.ts and symlink the checked out directories into the content directory. That will really simplify things because then we can just read all the docs with a single import.meta.glob. It's not really possible to simplify the import.meta.glob calls otherwise because they only work with static references to the paths. I could replace import.meta.glob with just scanning the filesystem to get rid of some of that duplication, but the result is passed to SvelteKit's read, which only works with imported Vite assets. And while we could swap read out for a call to node:fs, I wonder if read might work better in the future case that we want to include .svelte components in the docs. So symlinking seems like the simplest most future proof solution

Simon had a sync-docs.js script here that was used to create the _generated.md files, but that script is no longer working because it requires site-kit to be built first (to convert TS files to JS so that the JS file can call them), but that's something he wants to avoid. It also calls out to generate scripts that live in kit/sites/kit.svelte.dev and svelte/sites/svelte.dev, which is something that we should avoid so that we can delete those sites. We should move the generate scripts from those repos into this one. Hopefully they're not too different from one another and can be shared.

[dummdidumm]

I created #69 as an alternative, which I personally prefer over the "transient copy" approach

[benmccann]

I'll close this in favor of #69