More docs

CONTRIBUTING.md

@@ -1,51 +1,40 @@
 # Contributing to Theatre.js
 
-## The quick version
+## Development workflow
 
-Have `node 14+` and `yarn 1.22+` installed. Then `git clone` and `yarn install`. Then `cd packages/playground` and `yarn run serve`. Happy hacking!
+### Setting up the environment
-
-## The long version
-
-### Prerequisites
-
-Make sure you have [Node](https://nodejs.org/) installed at v14.0.0+
 
+Make sure you have [`node 14+`](https://nodejs.org/) installed:
 ```sh
 $ node -v
 > v14.0.0
 ```
 
-and [Yarn](https://classic.yarnpkg.com/en/) at v1.22.10+.
+and [`yarn 1.22+`](https://classic.yarnpkg.com/en/):
 
 ```sh
 $ yarn -v
 > 1.22.10
 ```
 
-> **Note about Yarn v2**: This repo uses Yarn v2. You don't have to install yarn v2 globally. If you do have yarn 1.22.10+ installed, and `cd` into `/path/to/theatre`, yarn will automatically switch to v2. Read more about Yarn v2 [here](https://yarnpkg.com/).
+Then clone the repo:
-
-### Fork, Clone & Install
-
-Start by forking Theatre.js to your GitHub account. Then clone your fork and install dependencies:
 
 ```sh
-$ git clone git@github.com:<your-user>/theatre.git
+$ git clone git@github.com:AriaMinaei/theatre.git
 $ cd theatre
+```
+
+And fetch the dependencies with yarn:
+
+```sh
 $ yarn
 ```
 
-> ⚠ theatre relies on
+* Notes about Yarn:
-> [yarn workspaces](https://yarnpkg.com/features/workspaces) so
+  * This project uses [yarn workspaces](https://yarnpkg.com/features/workspaces) so `npm install` will not work.
-> `npm install` will not work in this repository.
+  * This repo uses Yarn v2. You don't have to install yarn v2 globally. If you do have yarn 1.22.10+ on your machine, yarn will automatically switch to v2 when you `cd` into theatre. Read more about Yarn v2 [here](https://yarnpkg.com/).
 
-Add our repo as a git remote so you can pull/rebase your fork with our latest
+### Hacking with `playground`
-updates:
-
-```sh
-$ git remote add upstream git@github.com:AriaMinaei/theatre.git
-```
-
-## Start hacking with `playground`
 
 The quickest way to start tweaking things is to run the `playground` package.
 
@@ -60,48 +49,130 @@ It uses a single ESBuild config to build all of the related packages in one go,
 
 Read more at [`./packages/playground/README.md`](./packages/playground/README.md).
 
+### Hacking with `examples/`
+
+Other than `playground`, the [`examples/`](./examples) folder contains a few small projects that use Theatre with [parcel](https://parceljs.org), [Create react app](create-react-app.dev), and other build tools. This means that unlike `playground`, you have to build all the packages before running the examples.
+
+You can do that by running the `build` command at the root of the repo:
+
+```sh
+$ yarn build
+```
+
+Then build any of the examples:
+```
+$ cd examples/dom-cra
+$ yarn start
+```
+
+### Running tests
+
+We use a single [jest](https://jestjs.io/) setup for the repo. The tests files have the `.test.ts` or `.test.tsx` extension.
+
+You can run the tests at the root of the repo:
+
+```sh
+$ yarn test
+
+# or run them in watch mode:
+$ yarn test --watch
+```
+
+### Type checking
+
+The packages in this repo have full typescript coverage, so you should be able to get diagnostics and intellisense if your editor supports typescript.
+
+You can also run a typecheck of the whole repo from the root:
+
+```sh
+$ yarn typecheck
+
+# or in watch mode:
+$ yarn typecheck --watch
+```
+
+* If you're using VSCode, we have a ["Typescript watch"](./.vscode/tasks.json) task for VSCode that you can use by [running](https://code.visualstudio.com/Docs/editor/tasks) "Run Task -> Typescript watch".
+* If you wish to contribute code without typescript annotations, that's totally fine. We're happy to add the annotations to your PR.
+
+### Linting
+
+We're using a minimal [ESLint](https://code.visualstudio.com/Docs/editor/tasks) setup for linting. If your editor supports ESLint, you should get diagnostics as you code. You can also run the lint command from the root of the repo:
+
+```sh
+$ yarn lint:all
+```
+
+Some lint rules have [autofix](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems), so you can run:
+
+```sh
+$ yarn lint:all --fix
+```
+
+### Publishing to npm
+
+Currently all packages (except for [`@theatre/r3f`](./packages/r3f/)) share the same version number. In order to publish to npm, you can run the `release` script from the root of the repo:
+
+```sh
+$ yarn release x.y.z # npm publish version x.y.z
+$ yarn release x.y.z-dev.w # npm publish version x.y.z-dev.w and tag it as "dev"
+$ yarn release x.y.z-rc.w # npm publish version x.y.z-rc.w and tag it as "rc"
+```
+
+### Generating API docs
+
+We use [API extractor](https://api-extractor.com/pages/setup/generating_docs/) to generate API docs in markdown. We put the markdown files in the [theatre-docs](https://github.com/ariaminaei/theatre-docs/) repo, which also contains the tutorials and guides.
+
+To generate the API docs, run the `build:api-docs` from the root of the repo:
+
+```sh
+$ yarn build:api-docs /path/to/theatre-docs/docs/api/ # this will empty the /api folder and regenerate the markdown files
+```
+
 ## Project structure
 
-* `@theatre/core` – The core animation library.
+The [monorepo](https://en.wikipedia.org/wiki/Monorepo) consists of:
-  * Location: [`./theatre/core`](./theatre/core)
-* `@theatre/studio` – The visual editor.
-  * Location: [`./theatre/studio`](./theatre/studio)
-* `@theatre/dataverse` – The reactive dataflow library.
-  * Location: [`./packages/dataverse`](./packages/dataverse)
-* `@theatre/react` – Utilities for using Theatre with React.
-  * Location: [`./packages/react`](./packages/react)
-* `@theatre/r3f` – The react-three-fiber extension.
-  * Location: [`./packages/r3f`](./packages/r3f)
-* `playground` – The quickest way to hack on the internals of Theatre. It bundles all the related packages together with one ESBuild setup.
-  * Location: [`./packages/playground`](./packages/playground)
-* `examples/` * A bunch of examples, using Theatre with [parcel](https://parceljs.org), [Create react app](create-react-app.dev), etc.
-* `*/devEnv`: Each package may have a `devEnv` folder that holds dev-related files, like bundler configuration, lint config, etc.
 
+* `@theatre/core` – The core animation library at [`./theatre/core`](./theatre/core).
+* `@theatre/studio` – The visual editor at [`./theatre/studio`](./theatre/studio).
+* `@theatre/dataverse` – The reactive dataflow library at [`./packages/dataverse`](./packages/dataverse).
+* `@theatre/react` – Utilities for using Theatre with React at [`./packages/react`](./packages/react).
+* `@theatre/r3f` – The react-three-fiber extension at [`./packages/r3f`](./packages/r3f).
+* `playground` – The playground explained [above](#hacking-with-playground), located at [`./packages/playground`](./packages/playground)
+* `examples/` * A bunch of [examples](#hacking-with-examples) at [./examples](./examples).
 
-### Commands
+In addition, each package may contain a `dotEnv/` folder that holds some dev-related files, like bundle configuration, lint setup, etc.
 
-#### Root commands
+## Commands
 
 These commands are available at the root workspace:
 
 ```sh
 # Run the playground. It's a shortcut for `cd ./playground; yarn run serve`
-yarn playground
+$ yarn playground
 
 # Run all the tests.
-yarn test
+$ yarn test
 
 # Run tests in watch mode.
-yarn test --watch
+$ yarn test --watch
 
 # Typecheck all the packages
-yarn typecheck
+$ yarn typecheck
+
+# Typecheck all the packages in watch mode
+$ yarn typecheck --watch
 
 # Run eslint on the repo
-yarn lint:all
+$ yarn lint:all
 
 # Run eslint and auto fix
-yarn lint:all --fix
+$ yarn lint:all --fix
+
+# Build all the packages
+$ yarn build
+
+# Build the api documentation
+$ yarn build:api-docs /path/to/theatre-docs/docs/api/
 ```
 
 > Yarn passes all extra parameters to the internal scripts. So, for example, if you wish to run the tests in watch mode, you can run `yarn test --watch`.
@@ -113,22 +184,5 @@ The libraries come bundled with typescript definitions with TSDoc comments. You
 Other references
 
 - [Documentation: https://docs.theatrejs.com](https://docs.theatrejs.com/getting-started/)
+- [API docs: https://docs.theatrejs.com/api/](https://docs.theatrejs.com/api/)
 - [Video: Theatre.js Crash Course](https://www.youtube.com/watch?v=icR9EIS1q34)
-
-## Testing
-
-Run tests during development with `yarn test --watch` to re-run tests on file changes.
-
-### Examples
-
-Other than `playground`, the [`examples/`](./examples) folder contains a few small projects using the bundled version of the library. This means that unlike `playground`, you have to build all the packages before running the examples.
-
-## Releasing
-
-Currently all packages (except for [`@theatre/r3f`](./packages/r3f/)) share the same version number. In order to publish to npm, you can run the `release` script from the root of the repo:
-
-```sh
-$ yarn release x.y.z # npm publish version x.y.z
-$ yarn release x.y.z-dev.w # npm publish version x.y.z-dev.w and tag it as "dev"
-$ yarn release x.y.z-rc.w # npm publish version x.y.z-rc.w and tag it as "rc"
-```

README.md

@@ -30,11 +30,41 @@ You can use Theatre.js to:
 
 ## Documentation and Tutorials
 
-You can find the documentation and video tutorials [here](https://docs.theatrejs.com).
+The docs are at [docs.theatrejs.com](https://docs.theatrejs.com):
 
-## Community
+* [Getting started](https://docs.theatrejs.com/getting-started/)
+* [In depth guide](https://docs.theatrejs.com/in-depth/)
+* [API docs](https://docs.theatrejs.com/in-depth/)
+* [Extensions](https://docs.theatrejs.com/extensions/)
+* [Video tutorials](https://www.youtube.com/channel/UCsp9XOCs8v2twyq5kMLzS2Q)
+  * [Crash course](https://www.youtube.com/watch?v=icR9EIS1q34)
+  * [Animating with music](https://www.youtube.com/watch?v=QoS4gMxwq_4)
+  * [Yuri Artiukh](https://twitter.com/akella)'s [stream](https://youtu.be/qmRqgFbNprM?t=3462) with a section on using Theatre with THREE.js
+  * \<Add your own tutorials here\>
 
-Join us on [Discord](https://discord.gg/bm9f8F9Y9N), follow the updates on [twitter](https://twitter.com/AriaMinaei) or write us an [email](mailto:hello@theatrejs.com).
+## Community and support
+
+Join our friendly community on [Discord](https://discord.gg/bm9f8F9Y9N), follow the updates on [twitter](https://twitter.com/AriaMinaei) or write us an [email](mailto:hello@theatrejs.com).
+
+## Development and contributing
+
+If you want to change the source of Theatre, have a look at the guide [here](./CONTRIBUTING.md).
+
+### Proposing fixes and changes
+
+You can always get help with bugfixes or discuss changes with our community on [Discord](https://discord.gg/bm9f8F9Y9N), or directly open an issue on Github.
+
+### Helping with outstanding issues
+
+Feel free to chime in on any [issue](https://github.com/AriaMinaei/theatre/issues). We have also labeled some issues with ["Help wanted"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22) or ["Good first issue"](https://github.com/AriaMinaei/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) if you're just getting started with the codebase.
+
+### Helping with documentation
+
+The documentation website's repo is [here](https://github.com/ariaminaei/theatre-docs/).
+
+### Writing/recording tutorials
+
+If you make tutorials or video content about Theare, tell us to showcase it here :)
 
 ## License
 

package.json

@@ -10,6 +10,7 @@
   "scripts": {
     "playground": "yarn workspace playground run serve",
     "typecheck": "yarn run build:ts",
+    "build": "zx scripts/build.mjs",
     "build:ts": "tsc --build ./devEnv/typecheck-all-projects/tsconfig.all.json",
     "test": "jest",
     "postinstall": "husky install",

scripts/build-api-docs.mjs

@@ -1,6 +1,11 @@
+/**
+ * This script generates API documentation files in the target folder.
+ * Usage: `$ yarn build:api-docs <path>` creates the .md files in <path>.
+ * Example: `$ yarn build:api-docs path/to/theatre-docs/docs/api/`
+ *
+ * Usually <path> is https://github.com/AriaMinaei/theatre-docs/tree/main/docs/api
+ */
 import path from 'path'
-import {readFileSync, writeFileSync} from 'fs'
-import {keyBy} from 'lodash-es'
 import {parse as parseJsonC} from 'jsonc-parser'
 ;(async function () {
   // better quote function from https://github.com/google/zx/pull/167

scripts/build.mjs

@@ -0,0 +1,40 @@
+/**
+ * Builds all the packages for production
+ */
+
+const packagesToBuild = [
+  'theatre',
+  '@theatre/dataverse',
+  '@theatre/react',
+  '@theatre/browser-bundles',
+  '@theatre/r3f',
+]
+
+;(async function () {
+  // better quote function from https://github.com/google/zx/pull/167
+  $.quote = function quote(arg) {
+    if (/^[a-z0-9/_.-]+$/i.test(arg)) {
+      return arg
+    }
+    return (
+      `$'` +
+      arg
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\f/g, '\\f')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t')
+        .replace(/\v/g, '\\v')
+        .replace(/\0/g, '\\0') +
+      `'`
+    )
+  }
+
+  await Promise.all([
+    $`yarn run buid:ts`,
+    ...packagesToBuild.map(
+      (workspace) => $`yarn workspace ${workspace} run build`,
+    ),
+  ])
+})()