More docs
This commit is contained in:
Aria Minaei
parent
59090320ea
commit
3ed7e6bf6c
5 changed files with 202 additions and 72 deletions
186
CONTRIBUTING.md
186
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!
|
||||
|
||||
## The long version
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Make sure you have [Node](https://nodejs.org/) installed at v14.0.0+
|
||||
### Setting up the environment
|
||||
|
||||
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/).
|
||||
|
||||
### Fork, Clone & Install
|
||||
|
||||
Start by forking Theatre.js to your GitHub account. Then clone your fork and install dependencies:
|
||||
Then clone the repo:
|
||||
|
||||
```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
|
||||
> [yarn workspaces](https://yarnpkg.com/features/workspaces) so
|
||||
> `npm install` will not work in this repository.
|
||||
* Notes about Yarn:
|
||||
* This project uses [yarn workspaces](https://yarnpkg.com/features/workspaces) so `npm install` will not work.
|
||||
* 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
|
||||
updates:
|
||||
|
||||
```sh
|
||||
$ git remote add upstream git@github.com:AriaMinaei/theatre.git
|
||||
```
|
||||
|
||||
## Start hacking with `playground`
|
||||
### 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.
|
||||
* 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.
|
||||
The [monorepo](https://en.wikipedia.org/wiki/Monorepo) consists of:
|
||||
|
||||
* `@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"
|
||||
```
|
||||
36
README.md
36
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
40
scripts/build.mjs
Normal file
40
scripts/build.mjs
Normal file
|
|
@ -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`,
|
||||
),
|
||||
])
|
||||
})()
|
||||
Loading…
Reference in a new issue