-
Notifications
You must be signed in to change notification settings - Fork 0
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
Generate documentation page with JSDoc #2
Comments
Status update: So the two options of JSDoc and Sveld for getting the docs stuff out quickly and easily are not going to work in this situation. JSdoc is only going to work on .js files or TS that has been transpiled like you would get in a Vite/esbuild pipeline and likewise Sveld runs as a scanner of Svelte components which is not really applicable in this pure TS environment. So the obvious route forward is to look into TSDoc with it's API extractor https://api-extractor.com/pages/overview/intro/ (the doc model) and the typedoc project https://typedoc.org - both of which would give us a json summary of the classes/doc comments for displaying in the pages. I've setup both of them and they both fail. They start failing on:
And then continues with a lot more errors. Basically the @ts-nocheck might stop things being annoying during dev, but the errors it is reporting are real and need to be solved if we want to use any of the TS tooling to assist us. I don't know if this is a quick fix where fixing 1 or 2 references/types or something like that solves the bulk of the 27 issues reported in geometry.ts : So for now I'm going to pause on looking any further into this until I get some feedback on the TS issues. |
Hi, Just pushed the feat/doc-generation branch as a status update. You can run I had hoped that it would be able to do parsing with just a file or two, but because it is also doing full type checking, it has to consume all the referenced files, so it encountered some more TS issues. I've made some modifications to the source files and annotated them with TODO: to show where those changes are - as well as a hackish change on the bundle.d.ts imports that will get overwritten the next time the build script is run. As another test I also added typedoc ( These changes are purely to get the api extraction working so that I can use the outputted .json file. They are not the changes that would actually be needed for the project. When you get a chance, it would probably be best to bring a copy of /src/* from the main branch over the version in this branch and resolve the TS issues. Cheers, |
Worth looking into: |
Hey @ghostdevv ! Yeah that looks great for the next step (how it has zero stars is beyond me), but I think all the tools are kind of stuck till the TS issues are resolved.
|
I just pushed fixes for the TS errors and circular imports.
And the Still, it feels good for those stubborn TS errors to be gone from VsCode. Let me know if there's more I need to do to unblock you. |
So I just want to preface this update, this is turning about to be quite a different approach than what we took with the Skeleton docs where we basically used a vite plugin to extract the docs and we were also extracting from svelte components. Having said that - this is still relevant to the stuff I'm working on and I'm happy to keep exploring this. Thanks for getting the TS issues fixed! There is still something going on with the d.ts being generated into build/bundle.d.ts - the latest commit has the slight correction in it, but lets walk through what's happening. Running export { Geometry, Animation, Text, Scene, THREE, Utils, Diagram, Constants, setCameraDimensions, setCanvasViewport };
//export type { StudioScene, AnimationRepresentation }; Will now allow At this point I recommend At the top of the console you will see that I've added some dummy TSDoc annotations to the Animation constructor to see how they would come through. And whilst it comes through in the docComment field - none of the tags have been split out or presented in any useful manner. @ghostdevv I noticed that Extractinator uses the I've also stepped back and just tried to find any other tools that are oriented towards this problem and haven't really turned up much. But I'm completely open to any suggestions of other routes to look into - but my inclination is that sticking close to the TSDoc packages makes the most sense. Tomorrow i'll continue to explore the tsdoc packages as well and check out how Extractinator works too. |
I'm glad you were able to make some more progress! And that you got me to start taking those type errors more seriously 😅. You both have more experience with this than I do, but I'm getting the feeling that this task is for some reason more difficult with this codebase than it is on average. Does it seem that way to you? And if so, do you have any idea what might be causing it? When I started writing this I mostly just picked whatever typescript settings would get me up and running the fastest, so I don't know if it'd be better if I was to use |
Thanks! We only started making it recently
Could you try with version 0.3.0? |
Use JSDoc to generate a documentation page in svelte so that it can be added to the documentation page here. The goal is to have something similar to the one here. The webpage should:
Don't worry about the content of the website or complex styling, the main goal is just to be able to generate the site with templated pages for the classes. I'll also want a walkthrough on the tools used to generate the website and how I can extend/customize it with new classes or default values.
The text was updated successfully, but these errors were encountered: