Merge pull request #334 from tidalcycles/docs

testing + docs docs

website/src/components/PageContent/PageContent.astro

@@ -21,7 +21,7 @@ const title = frontmatter.title;
       <span>On this Page:</span>
       <TableOfContents client:media="(max-width: 50em)" headings={headings} />
     </nav> -->
-    <div class="prose prose-invert max-w-full">
+    <div class="prose prose-invert max-w-full pb-8">
       <slot />
     </div>
   </section>

website/src/config.ts

@@ -61,6 +61,8 @@ export const SIDEBAR: Sidebar = {
       { text: 'Patterns', link: 'technical-manual/patterns' },
       { text: 'REPL', link: 'technical-manual/repl' },
       { text: 'Pattern Alignment', link: 'technical-manual/alignment' },
+      { text: 'Docs', link: 'technical-manual/docs' },
+      { text: 'Testing', link: 'technical-manual/testing' },
     ],
   },
 };

website/src/pages/technical-manual/docs.mdx

@@ -1 +1,71 @@
-TODO
+---
+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
+- `withCanvas`: If set, a canvas will be rendered below that shows a pianoroll (WIP)
+
+## 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.
+
+### 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

website/src/pages/technical-manual/testing.mdx

@@ -0,0 +1,27 @@
+---
+title: Testing
+layout: ../../layouts/MainLayout.astro
+---
+
+# Testing
+
+Strudel uses [vitest](https://vitest.dev/) for testing, with 2 types of testing strategies:
+
+- unit tests for fine grained testing
+- automated snapshot tests for broader testing
+
+## Unit Tests
+
+Each package has a `test` folder where tests are written on a file by file basis, e.g. `util.test.mjs` implements all tests for `util.mjs`.
+
+## Snapshot Tests
+
+Snapshot tests allow testing larger chunks of data. Strudel uses snapshot tests for:
+
+- Example Snippets: `examples.test.mjs`, using snippets under `@example` inside jsdoc comments
+- Example Tunes: `tunes.test.mjs`, using all patterns in `tunes.mjs`
+
+The snapshot (`.snap`) files contain all haps within a certain number of cycles for each tested pattern.
+They allow testing for breaking changes on a larger scale.
+If breaking changes are intentional, the snapshots can be updated with `npm run snapshot`.
+Just make sure to verify that all affected patterns behave as expected.

website/src/pages/technical-manual/tests.mdx

@@ -1 +0,0 @@
-TODO