Better way to build docs

[fenomas]

This project needs docs! Most of the public methods have up-to-date JSDoc-style headers, and I'm pretty good about keeping them in sync with the implementations, but I never worked out a decent way of building the JSDocs into clean readable markdown or html. If anyone wants to tackle this it'd be cool 😁

[masonmahaffey]

I'd love to contribute to the documentation as I use the engine and learn more about it! Are you planning on adding this into the main readme or a readme in the docs folder?

[fenomas]

No idea really 😁 Probably there'd be too many docs to go in the main readme, so a folder full of md files that link to each other might be best. But really anything that parses jsdoc comments and makes a nice readable result would be okay with me. I worked on this once (see here) but something broke and I didn't have time to get into it.

[masonmahaffey]

Awesome, ill start adding documentation as I continue to work on my project, ill let you take a look and see what you think at some point. I've already built a tree diagram for several functions just for myself so we could add that into the documentation as well to show the function hierarchy for different functionalities. I simply did it for my own sanity when trying to better understand how things like chunks are managed in the engine. ;O

[fenomas]

Sorry, I should clarify - what I was specifically hoping for is help with a JSDoc-style build system. JSDoc is the thing where you add specially formatted comments to the code, like:

/** 
 * @param foo: [string] the name of the thing
 */

and then use some library that parses all the code and auto-generates an API reference of some kind.

I had something like this working at some point, based on a library called markdox, but something broke and I wasn't that happy with it anyway, and haven't had time to look for something better.

[masonmahaffey]

Wow I had no idea that was even a thing, that's pretty cool. I'll have to read about how that works.

[2ajoyce]

It doesn't seem like this has been worked on so far. Would this do what you want @andyhall? https://github.com/jsdoc2md/jsdoc-to-markdown

[icopp]

Typedoc might be useful (there's a supported Webpack plugin), but it would take switching the code to Typescript first.

[fenomas]

Newest build in the #dev branch now has this partly working - it uses jsdoc-to-markdown (thanks @2ajoyce !) and builds reasonably sane output. But some comments could use work, so any doc fix PRs are very welcome!

To use check out the dev branch, do npm i, and then npm run doc should rebuild API.md.