proper docs

[felixroos]

At some point, it would be good to have a proper docs website that is more than just a giant document. Especially as the API grows, a single document is too large.
Similar to tidal docs, we could use docusaurus for that, as it also supports MDX, which allows embedding the MiniREPL.

Probably wait for #91

[yaxu]

How about embedding some docs in the source, is that often done in javascript land?

[felixroos]

yes, it would be good to have a little doc comment over each function. I also thought we could parse those out and generate an API doc, which should be a seperate thing from the tutorial

[yaxu]

I think we should add docusaurus to the monorepo then. I think it's possible to have more than one github pages site, by having the build folder a submodule. That said, probably best to build to /docs, and move the tutorial into docusaurus?

[yaxu]

It would be good to move on this so as to not get too behind with documenting all these functions. I'm not good at the documentation habit but can imagine trying to add a simple test and documentation file for each function as a minimum.

I'm not sure how to quickly get started though. Maybe just add a vanilla docusaurus site under /docusaurus and start adding stuff to that, one file per function/set of functions as reference material? Then decide how to integrate with tutorial etc later?

[felixroos]

yes, it's time to catch up with documentation. It might be smart to document each function in source using jsdoc and converting that to docusaurus later, as the API docs. In addition, we can add more tutorial / guide like pages to the docs

[felixroos]

just tested jsdoc in in-source-doc branch. It allows generating api docs easily. though its type system is inferior to typescript. It can either render to html or markdown, and it should integrate easily with docusaurus. here is some example output: https://github.com/tidalcycles/strudel/blob/in-source-doc/api.md , generated from these changes 2348d05#diff-c8529a9530742d567d93fc894a928043a5356ff50e608d4130f80f5e6d4ac3de

[felixroos]

just tried jsdoc-json, which allows turning source comments into an easy to process json file:

strudel/doc.json

Line 1 in e0c77a5

{

that could be used to show dynamic tooltips in the editor, e.g. show the description of the params of a function while typing (by combining the user code AST with the params field)