Docs

The docs page is built ontop of astro’s docs site.

Adding a new Docs Page

  1. add a .mdx file in a path under website/src/pages/, e.g. website/src/pages/learn/code.mdx will be available under https://strudel.tidalcycles.org/learn/code (or locally under http://localhost:3000/learn/code)
  2. make sure to copy the top part of another existing docs page. Adjust the title accordingly
  3. To add a link to the sidebar, add a new entry to SIDEBAR to config.ts

Using the Mini REPL

To add a Mini REPL, make sure to import:

import { MiniRepl } from '../../docs/MiniRepl';

add a mini repl with

<MiniRepl client:idle tune={`note("a3 c#4 e4 a4")`} />
  • client:idle is required to tell astro that the repl should be interactive, see Client Directive
  • tune: be any valid pattern code
  • punchcard: if added, a punchcard / pianoroll visualization is renderd
  • drawTime: time window for drawing, defaults to [0, 4]
  • canvasHeight: height of the canvas, defaults to 100px

See mini-notation.mdx for usage examples

In-Source Documentation

You can add the in-source documentation for a function by using the JsDoc component. Import:

import { JsDoc } from '../../docs/JsDoc';

Usage:

<JsDoc client:idle name="bandf" h={0} />
  • name: function name, as named with @name in jsdoc
  • h: level of heading. 0 will hide the heading. Hiding it allows using a manual heading which results in a nav link being generated in the right sidebar.
  • hideDescription: if set, the description will be hidden

Writing jsdoc

Documentation is written with jsdoc comments. Example:

/**
 * Select a sound / sample by name.
 *
 * @name s
 * @param {string | Pattern} sound The sound / pattern of sounds to pick
 * @example
 * s("bd hh")
 *
 */
// implementation of s function
  • Before each build, these comments will be rendered into doc.json using jsdoc-json as a template
  • To regenerate the doc.json file manually, run npm run jsdoc-json
  • The file is used by the JsDoc component to find the documentation by name
  • Also, it is used for the examples.test.mjs snapshot test

How does Strudel do its Testing?