Skip to content

Sync generated docs into this repo #20

Closed
@dummdidumm

Description

@dummdidumm

Describe the problem

We have reference documentation inside JSDoc for Svelte and SvelteKit. They are extracted out into a specific structure in their respective modules and then fed to the markdown renderer that's located in site-kit. This JSDoc should stay the source of truth, which means we need bring them over somehow into this repo. The result of this pulling-in of JSDoc should be committed into this repository so that it's easy to deploy (no need to pull together repositories on the fly when building; we can control when to update). The result should also be readable / be in a format that is eventually easily translateable (that means just committing the giant JSON file would not be enough).

Describe the proposed solution

  • set up a script you can run locally that pulls in the jsdoc which is in repositories on your disk
  • the output format is .md files using a certain structure. Example
---
name: "$app/environment"
---

some text about the module as a whole

## browser

\`\`\`
const browser: boolean;
\`\`\`

`true` if the app is running in the browser.

this makes translating and double-checking them much easier

  • new logic is written to read those .md files and convert them into the JSON structure we have today
  • from there on everything can be reused as today

Once this is setup and we have more time we can revisit the rendering chain and possibly refactor/remove some parts which may no longer be necessary. In the long run investigate something like mdsvex for additional flexibility and having interactive parts. Could also replace the somewhat implicit structure in those generated files with something more explicit.

Importance

i cannot use svelte without it

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions