mirror of
https://github.com/eliasstepanik/strudel-docker.git
synced 2026-01-14 07:08:30 +00:00
77 lines
2.5 KiB
Plaintext
77 lines
2.5 KiB
Plaintext
---
|
|
title: Docs
|
|
layout: ../../layouts/MainLayout.astro
|
|
---
|
|
|
|
# Docs
|
|
|
|
The docs page is built ontop of astro's [docs site](https://github.com/withastro/astro/tree/main/examples/docs).
|
|
|
|
## 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](https://raw.githubusercontent.com/tidalcycles/strudel/main/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`](https://github.com/tidalcycles/strudel/blob/main/website/src/config.ts)
|
|
|
|
## Using the Mini REPL
|
|
|
|
To add a Mini REPL, make sure to import:
|
|
|
|
```js
|
|
import { MiniRepl } from '../../docs/MiniRepl';
|
|
```
|
|
|
|
add a mini repl with
|
|
|
|
```jsx
|
|
<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](https://docs.astro.build/en/reference/directives-reference/#client-directives)
|
|
- `tune`: be any valid pattern code
|
|
- `drawTime`: time window for drawing. Use together with `.punchcard()`. Example:
|
|
|
|
```jsx
|
|
<MiniRepl client:idle tune={`note("a3 c#4 e4 a4").punchcard()`} drawTime={[0, 2]} />
|
|
```
|
|
|
|
## In-Source Documentation
|
|
|
|
You can add the in-source documentation for a function by using the `JsDoc` component. Import:
|
|
|
|
```js
|
|
import { JsDoc } from '../../docs/JsDoc';
|
|
```
|
|
|
|
Usage:
|
|
|
|
```jsx
|
|
<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](https://jsdoc.app/) comments. Example:
|
|
|
|
```js
|
|
/**
|
|
* 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](https://www.npmjs.com/package/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
|