flint otter
I'm using JSDoc to document the project I'm working on. I'd like to integrate it's generated output files for my API documentation. Does anyone have a workflow or solution for doing this?
I can drop the generated files into ./src/pages, but of course they don't match up with Astro / Starlight theming. I know that JSDoc can be configured to theme it's output files. Has anyone ever attempted an integration like this?
robust sable
is the output normal markdown? if so, you should be able to drop them in src/content/docs for starlight, or look at content collections for something in a custom astro site
https://docs.astro.build/en/guides/content-collections/
flint otter
is the output normal markdown? if so, you should be able to drop them in `src/co...
I found this tool, documentation.js https://documentation.js.org which works with JSDoc. You can get raw documentation as JSON, HTML, or Markdown.
The output can be directed to a content collection which would automate the whole process...
although Astro demands a header with a title, so I have to dig into documentation.js further to see if this is possible.
lilac spruce
Not sure if it’s exactly what you’re looking for, but there’s also this integration by a community member: https://github.com/HiDeoo/starlight-typedoc
flint otter
Not sure if it’s exactly what you’re looking for, but there’s also this integrat...
Thank you for the suggestion Chris. I'll look into it.
I'm currently testing out Astro, and learning its ins and outs. My end goal is to use it to generate the documentation for an open source project that I am building. So the two are separate at the moment.
Is there a strategy where I can have Astro integrated into my project to better automate documentation generation, via a tool such as the one you suggested above?
Can or should I install it into my project, or should I keep it separate? Pros and cons?
lilac spruce
My usual approach is to have a “monorepo” for these cases. Usually with a docs/ directory for the docs site and one or more package directories for the project code. In fact that’s the same model Starlight follows: the npm package we publish lives in packages/starlight/ and the docs site lives in docs/. That should mean you can generate stuff based on your code directly to docs/ without the headache of trying to keep multiple repositories in sync.
The caveat would be for really big projects. For example for Astro’s main docs we have so much activity focused just on documentation (we just saw more than 20 PRs in a day 😅), so we decided it’s easier to have a dedicated docs repo. But that’s a move I’d generally suggest later on if it becomes necessary for organisation reasons.
flint otter
OK, so if I integrate it directly into my project, I would then follow the manual installation guidelines then?
lilac spruce
Not necessarily. What does your project look like right now?
You can probably run the create astro wizard and choose to create the new site in /docs: https://starlight.astro.build/getting-started/#creating-a-new-project
flint otter
Here's the current repo for the project:
https://github.com/tradex-app/TradeX-chart/tree/master
It builds a JavaScript library, published to NPM.
I'd like to use ./docs as the documentation deployment directory, because I can then point the GitHub Project page to that directory.
What would be your suggestion as to how to integrate Astro into this project?
./docs assuming that Astro will not be located in the root as normal when it is the primary project.