Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Move detailed docs to vitepress #131

Open
claytercek opened this issue Sep 19, 2023 Discussed in #116 · 3 comments
Open

Move detailed docs to vitepress #131

claytercek opened this issue Sep 19, 2023 Discussed in #116 · 3 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@claytercek
Copy link
Member

Discussed in #116

@claytercek claytercek added the documentation Improvements or additions to documentation label Sep 19, 2023
@claytercek claytercek self-assigned this Sep 19, 2023
@claytercek
Copy link
Member Author

@benjaminbojko Looks like reimplementing the autogenerated docs will be a bit more difficult than anticipated. There are a couple of approaches, but none seem to fully match our needs:

  • use the TS compiler to manually extract the type info from a given file, then pass that json to vitepress and display with custom components. Here's an example that shows how one can get the constructor info from the classes in a file as json: https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API#using-the-type-checker – this gets complicated, as JSDoc isn't included in the AST
  • use typedoc to generate a JSON file with all type info for the whole repo, then collect the relevant json from that larger set and pass it to vitepress to be rendered via custom components. This is pretty unwieldy - just for the content package, it dumps out 25k lines of JSON, with types fragmented across the whole thing.

Overall both options could potentially work, but getting either setup will take a good chunk of time. I'm not sure that the benefit of automation here outweighs the cost of dev and maintenance when compared to just manually writing up the markdown files.

@benjaminbojko
Copy link
Collaborator

Oof yeah. It was nice to have all the various options listed out, but the main challenge with our docs is actually making it clear how to fit all the pieces together.

I think with #116 and the new config autocomplete, we can probably make the documentation more focused on use cases, principles, etc. Let's close this one as won't fix.

@benjaminbojko benjaminbojko closed this as not planned Won't fix, can't repro, duplicate, stale Sep 21, 2023
@benjaminbojko benjaminbojko reopened this Sep 21, 2023
@benjaminbojko
Copy link
Collaborator

Whoops realized that this was the larger vitepress issue and not just for jsdocs :)

We should continue with vitepress, but remove all dependencies to jsdocs (scripts, templates, etc).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

When branches are created from issues, their pull requests are automatically linked.

2 participants