In source doc

[felixroos]

No description provided.

[yaxu]

Awesome stuff! Some thoughts looking through..

• It would be really great to add percussive examples. We could have drum kit names for this (bd = bass drum, sn = snare, cp = clap etc) with default samples loaded
• E.g. commas aren't just for chords, but polyphony in general, and especially polymeter. It'd be easier to exemplify that with drums I think
• The descriptions are short but really clear I think, with the examples doing a lot of good work. it'll be interesting seeing how beginners find it
• I think many will see 'API' as jargon, and kind of is the wrong term (for end-user not application programming), worth replacing it in the tutorial/mainstream docs at least
• Maybe the jsdoc 'api docs' appendix should be separate on a different page. A beginner might happen across it and get confused. Having it visible is definitely motivating for fixing it up and writing more!
• Having the ability to include jsdoc fragments in the mainstream docs/tutorial would be good for avoiding duplication of effort / hard to maintain copy-pasting

[felixroos]

It would be really great to add percussive examples. We could have drum kit names for this (bd = bass drum, sn = snare, cp = clap etc) with default samples loaded

Good idea. I'd say we can add a default drum kit, which is implicitly loaded (to make the examples shorter). We can then add melodic + rhythmic examples. As the default drum kit will be loaded with the page, we should only add a handful of sounds to keep the traffic low (especially for mobile).

Additionally, it would be handy if there was a quick way to load sample packs explicitly, like loadSamples(<githuburl>), but this should be a separate issue / PR.

Maybe the jsdoc 'api docs' appendix should be separate on a different page. A beginner might happen across it and get confused. Having it visible is definitely motivating for fixing it up and writing more!

Yes, it might be confusing, especially because the order is kind of random and not really didactic. There should be a separation between guide / tutorial and api docs. For now I just wanted to add them somewhere, in the future we'll probably have a proper docs site with routing. In the meantime, we could also "hide" it further by throwing it into a details tag (https://www.w3schools.com/tags/tag_details.asp).

Having the ability to include jsdoc fragments in the mainstream docs/tutorial would be good for avoiding duplication of effort / hard to maintain copy-pasting

yes this is absolutely possible right now with the custom jsdoc renderer. we could throw a <ApiDoc name="slowcat"/> inside the tutorial somewhere to render it wherever we want.

Also, I want to investigate a way to show dynamic tooltips / sidebar info inside the repl when the cursor is placed over a function that is documented.

[felixroos]

I have now changed the way the api docs are rendered:

• Instead of rendering the complete jsdoc json in a chaotic order (determined by the order jsdoc reads the source files), I am now using nunjucks to selectively render jsdoc entries to specific points in the document
• you can see how it looks before rendering here: https://github.com/tidalcycles/strudel/blob/in-source-doc/tutorial/tutorial.mdx#api-docs
• on each build, those variables are automatically rendered with the latest jsdoc contents
• this is the current output: https://strudel.tidalcycles.org/tutorial/#api-docs
• this allows to structure the api docs as it makes the most sense + it allows to only add the functions we really want to appear here

Having the ability to include jsdoc fragments in the mainstream docs/tutorial would be good for avoiding duplication of effort / hard to maintain copy-pasting

this is now also possible. Although I think it can make sense at times to have some duplication as part of a guide with a "golden thread", where the choice of words is specifically tailored to the story of the guide (which shouldn't be part of jsdoc comments).

[felixroos]

sample support will be better with #121 so then we can use them in the minirepl

[felixroos]

I'll merge this for now, to clean up the webdirt branch, will open new PR when rest is added