README: add theatre logo. Add/fix social links (#113)
* add theatre logo. Add/fix social links * remove styles that don't work in github md * Add more detailed getting started links to README * change github links to use theatre-js org and autoformat
This commit is contained in:
Elliot
GitHub
parent
f1a1f48c0f
commit
0cc4f795a1
5 changed files with 203 additions and 91 deletions
131
CONTRIBUTING.md
131
CONTRIBUTING.md
|
|
@ -5,6 +5,7 @@
|
|||
### Setting up the environment
|
||||
|
||||
Make sure you have [`node 14+`](https://nodejs.org/) installed:
|
||||
|
||||
```sh
|
||||
$ node -v
|
||||
> v14.0.0
|
||||
|
|
@ -20,7 +21,11 @@ $ yarn -v
|
|||
Then clone the repo:
|
||||
|
||||
```sh
|
||||
$ git clone git@github.com:AriaMinaei/theatre.git
|
||||
# for SSH:
|
||||
$ git clone git@github.com:<github-username>/theatre.git
|
||||
# for HTTPS:
|
||||
$ git clone https://github.com/<github-username>/theatre.git
|
||||
|
||||
$ cd theatre
|
||||
```
|
||||
|
||||
|
|
@ -30,9 +35,13 @@ And fetch the dependencies with yarn:
|
|||
$ yarn
|
||||
```
|
||||
|
||||
* 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/).
|
||||
- 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/).
|
||||
|
||||
### Hacking with `playground`
|
||||
|
||||
|
|
@ -46,13 +55,19 @@ $ cd root
|
|||
$ yarn playground
|
||||
```
|
||||
|
||||
The playground is a bunch of ready-made projects that you can run to experiment with Theatre.js. It also contains the project's end-to-end tests.
|
||||
The playground is a bunch of ready-made projects that you can run to experiment
|
||||
with Theatre.js. It also contains the project's end-to-end tests.
|
||||
|
||||
Read more at [`./packages/playground/README.md`](./packages/playground/README.md).
|
||||
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.
|
||||
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:
|
||||
|
||||
|
|
@ -61,6 +76,7 @@ $ yarn build
|
|||
```
|
||||
|
||||
Then build any of the examples:
|
||||
|
||||
```
|
||||
$ cd examples/dom-cra
|
||||
$ yarn start
|
||||
|
|
@ -68,7 +84,8 @@ $ yarn start
|
|||
|
||||
### Running unit/integration tests
|
||||
|
||||
We use a single [jest](https://jestjs.io/) setup for the repo. The tests files have the `.test.ts` or `.test.tsx` extension.
|
||||
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:
|
||||
|
||||
|
|
@ -81,11 +98,13 @@ $ yarn test --watch
|
|||
|
||||
### Running end-to-end tests
|
||||
|
||||
End-to-end tests are hosted in the playground package. More details [there](./packages/playground/README.md).
|
||||
End-to-end tests are hosted in the playground package. More details
|
||||
[there](./packages/playground/README.md).
|
||||
|
||||
### 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.
|
||||
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:
|
||||
|
||||
|
|
@ -96,18 +115,26 @@ $ yarn typecheck
|
|||
$ 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.
|
||||
- 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:
|
||||
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:
|
||||
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
|
||||
|
|
@ -115,7 +142,9 @@ $ 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:
|
||||
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
|
||||
|
|
@ -125,7 +154,10 @@ $ 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.
|
||||
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/theatre-js/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:
|
||||
|
||||
|
|
@ -139,15 +171,23 @@ Learn more about api documentation [here](./contributing/api-docs.md).
|
|||
|
||||
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).
|
||||
- `@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).
|
||||
|
||||
In addition, each package may contain a `dotEnv/` folder that holds some dev-related files, like bundle configuration, lint setup, etc.
|
||||
In addition, each package may contain a `dotEnv/` folder that holds some
|
||||
dev-related files, like bundle configuration, lint setup, etc.
|
||||
|
||||
## Commands
|
||||
|
||||
|
|
@ -182,11 +222,13 @@ $ yarn build
|
|||
$ 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`.
|
||||
> 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`.
|
||||
|
||||
## Documentation
|
||||
|
||||
The libraries come bundled with typescript definitions with TSDoc comments. You can explore the API if your editor is configured to display TSDoc comments.
|
||||
The libraries come bundled with typescript definitions with TSDoc comments. You
|
||||
can explore the API if your editor is configured to display TSDoc comments.
|
||||
|
||||
Other references
|
||||
|
||||
|
|
@ -198,25 +240,36 @@ Other references
|
|||
|
||||
You can contribute with:
|
||||
|
||||
* Bug fixes
|
||||
* Feature suggestions
|
||||
* Features implementations
|
||||
* [Documentation](https://github.com/ariaminaei/theatre-docs/) (or write/record tutorials of your own which we'll showcase)
|
||||
* Create examples projects for your own particular dev stack (eg. using Pixie/Vue/THREE.js/Babylon/etc)
|
||||
- Bug fixes
|
||||
- Feature suggestions
|
||||
- Features implementations
|
||||
- [Documentation](https://github.com/theatre-js/theatre-docs/) (or write/record
|
||||
tutorials of your own which we'll showcase)
|
||||
- Create examples projects for your own particular dev stack (eg. using
|
||||
Pixie/Vue/THREE.js/Babylon/etc)
|
||||
|
||||
Another great way to help is to join our [community](https://discord.gg/bm9f8F9Y9N) and chime in on questions and share ideas.
|
||||
Another great way to help is to join our
|
||||
[community](https://discord.gg/bm9f8F9Y9N) and chime in on questions and share
|
||||
ideas.
|
||||
|
||||
### Helping with outstanding issues
|
||||
|
||||
Feel free to chime in on any [issue](https://github.com/AriaMinaei/theatre/issues). We have labeled some 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.
|
||||
Feel free to chime in on any
|
||||
[issue](https://github.com/theatre-js/theatre/issues). We have labeled some with
|
||||
["Help wanted"](https://github.com/theatre-js/theatre/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22help+wanted%22)
|
||||
or
|
||||
["Good first issue"](https://github.com/theatre-js/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.
|
||||
|
||||
## Sending pull requests
|
||||
|
||||
We use Github's regular PR workflow. Basically fork the repo, push your commits, and send a pull request.
|
||||
We use Github's regular PR workflow. Basically fork the repo, push your commits,
|
||||
and send a pull request.
|
||||
|
||||
If you're a core contributor and have write access to the repo, you should submit your pull requests from a branch
|
||||
rather than a personal fork. The naming convention for these branches should be:
|
||||
If you're a core contributor and have write access to the repo, you should
|
||||
submit your pull requests from a branch rather than a personal fork. The naming
|
||||
convention for these branches should be:
|
||||
|
||||
* `(feature|hotfix|docs)/[identifier]`
|
||||
or
|
||||
* an autogenerated branch name from a Github issue (On an issue without a PR, look under the "Development" sidebar heading for a "create a branch link")
|
||||
- `(feature|hotfix|docs)/[identifier]` or
|
||||
- an autogenerated branch name from a Github issue (On an issue without a PR,
|
||||
look under the "Development" sidebar heading for a "create a branch link")
|
||||
|
|
|
|||
96
README.md
96
README.md
|
|
@ -1,35 +1,54 @@
|
|||
# Theatre.js
|
||||
<h1 align="center">
|
||||
<img src="https://docs.theatrejs.com/public/theatrejs-logo-black.svg" alt="Theatre.js" width="200">
|
||||
</h1>
|
||||
<p align="center">Motion Design, for the web</p>
|
||||
<p align="center">
|
||||
<a href="https://discord.gg/Tku4CJKf4B">
|
||||
<img src="https://img.shields.io/discord/870988717190426644?label=Discord" alt="Join us on Discord">
|
||||
</a> ⎯◈⎯
|
||||
<a href="https://twitter.com/theatre_js">
|
||||
<img src="https://img.shields.io/twitter/follow/theatre_js?style=social" alt="Follow us on Twitter">
|
||||
</a> ⎯◈⎯
|
||||
<a href="https://www.youtube.com/channel/UCsp9XOCs8v2twyq5kMLzS2Q">
|
||||
<img src="https://img.shields.io/youtube/channel/views/UCsp9XOCs8v2twyq5kMLzS2Q?label=TheatreJS&style=social" alt="Watch on YouTube">
|
||||
</a> ⎯◈⎯
|
||||
<a href="https://theatrejs.com">
|
||||
<img src="https://docs.theatrejs.com/public/theatrejs-logo-black.svg" alt="TheatreJS" width="70">.com
|
||||
</a>
|
||||
</p>
|
||||
|
||||
> ✨ Update: [We're hiring – join the core team!](https://join.theatrejs.com/)
|
||||
|
||||
|
||||
|
||||
|
||||
Theatre.js is an animation library for high-fidelity motion graphics. It is designed to help you express detailed animation, enabling you to create intricate movement, and convey nuance.
|
||||
Theatre.js is an animation library for high-fidelity motion graphics. It is
|
||||
designed to help you express detailed animation, enabling you to create
|
||||
intricate movement, and convey nuance.
|
||||
|
||||
Theatre can be used both programmatically _and_ visually.
|
||||
|
||||
---
|
||||
|
||||
You can use Theatre.js to:
|
||||
|
||||
* Animate 3D objects made with THREE.js or other 3D libraries
|
||||
- Animate 3D objects made with THREE.js or other 3D libraries
|
||||
|
||||
|
||||
|
||||
<sub>Art by [drei.lu](https://sketchfab.com/models/91964c1ce1a34c3985b6257441efa500)</sub>
|
||||
<sub>Art by
|
||||
[drei.lu](https://sketchfab.com/models/91964c1ce1a34c3985b6257441efa500)</sub>
|
||||
|
||||
* Animate HTML/SVG via React or other libraries
|
||||
- Animate HTML/SVG via React or other libraries
|
||||
|
||||
|
||||
|
||||
* Design micro-interactions
|
||||
- Design micro-interactions
|
||||
|
||||
|
||||
|
||||
* Choreograph generative interactive art
|
||||
- Choreograph generative interactive art
|
||||
|
||||
|
||||
|
||||
* Or animate any other JS variable
|
||||
- Or animate any other JS variable
|
||||
|
||||
|
||||
|
||||
|
|
@ -37,43 +56,64 @@ You can use Theatre.js to:
|
|||
|
||||
The docs are at [docs.theatrejs.com](https://docs.theatrejs.com):
|
||||
|
||||
* [Getting started](https://docs.theatrejs.com/getting-started/)
|
||||
* [In depth guide](https://docs.theatrejs.com/in-depth/)
|
||||
* [API docs](https://docs.theatrejs.com/api/)
|
||||
* [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\>
|
||||
- [Getting started guide](https://docs.theatrejs.com/getting-started/)
|
||||
- [Install Theatre.js](https://docs.theatrejs.com/getting-started/install/)
|
||||
- [Quickly try Theatre.js out](https://docs.theatrejs.com/getting-started/try-it-out/)
|
||||
- [Learn the basics](https://docs.theatrejs.com/getting-started/basics/)
|
||||
- [In depth guide](https://docs.theatrejs.com/in-depth/)
|
||||
- [API docs](https://docs.theatrejs.com/api/)
|
||||
- [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\>
|
||||
|
||||
## 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).
|
||||
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).
|
||||
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.
|
||||
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.
|
||||
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/).
|
||||
The documentation website's repo is
|
||||
[here](https://github.com/theatre-js/theatre-docs/).
|
||||
|
||||
### Writing/recording tutorials
|
||||
|
||||
If you make tutorials or video content about Theatre, tell us to showcase it here :)
|
||||
If you make tutorials or video content about Theatre, tell us to showcase it
|
||||
here :)
|
||||
|
||||
## License
|
||||
|
||||
Your use of Theatre.js is governed under the Apache License Version 2.0:
|
||||
|
||||
* Theatre's core (`@theatre/core`) is released under the Apache License. Same goes for most packages in this repository.
|
||||
* The studio (`@theatre/studio`) is released under the AGPL 3.0 License. This is the package that you use to edit your animations, setup your scenes, etc. You only use the studio during design/development. Your project's final bundle only includes `@theatre/core`, so only the Apache License applies.
|
||||
- Theatre's core (`@theatre/core`) is released under the Apache License. Same
|
||||
goes for most packages in this repository.
|
||||
- The studio (`@theatre/studio`) is released under the AGPL 3.0 License. This is
|
||||
the package that you use to edit your animations, setup your scenes, etc. You
|
||||
only use the studio during design/development. Your project's final bundle
|
||||
only includes `@theatre/core`, so only the Apache License applies.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,9 @@
|
|||
# Writing 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.
|
||||
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/theatre-js/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:
|
||||
|
||||
|
|
@ -10,16 +13,20 @@ $ yarn build:api-docs /path/to/theatre-docs/docs/api/ # this will empty the /api
|
|||
|
||||
## JSDoc/TSDoc gotchas
|
||||
|
||||
We are using TSDoc for documentation generation, IDEs use JSDoc for tooltips. TSDoc and JSDoc have subtle differences. We need to optimize for both.
|
||||
We are using TSDoc for documentation generation, IDEs use JSDoc for tooltips.
|
||||
TSDoc and JSDoc have subtle differences. We need to optimize for both.
|
||||
|
||||
Most users will read our documentation inside their IDEs.
|
||||
|
||||
### `@example`
|
||||
|
||||
IDEs automatically wrap example sections in `` ``` `` if they aren't already wrapped by you. This means you can't use non-code explanations in example sections, like TSDoc examples do.
|
||||
IDEs automatically wrap example sections in ` ``` ` if they aren't already
|
||||
wrapped by you. This means you can't use non-code explanations in example
|
||||
sections, like TSDoc examples do.
|
||||
|
||||
This will be formatted incorrectly:
|
||||
```ts
|
||||
|
||||
````ts
|
||||
/**
|
||||
* Adds two numbers together.
|
||||
* @example
|
||||
|
|
@ -35,42 +42,54 @@ This will be formatted incorrectly:
|
|||
* console.log(add(1,-1));
|
||||
* ```
|
||||
*/
|
||||
export function add(x: number, y: number): number {
|
||||
}
|
||||
```
|
||||
export function add(x: number, y: number): number {}
|
||||
````
|
||||
|
||||
Some IDEs have problems with having multiple example sections in the same JSDoc comment.
|
||||
Some IDEs have problems with having multiple example sections in the same JSDoc
|
||||
comment.
|
||||
|
||||
WebStorm doesn’t highlight examples if you wrap them in `` ``` ``.
|
||||
WebStorm doesn’t highlight examples if you wrap them in ` ``` `.
|
||||
|
||||
api-documenter doesn’t highlight examples if you don't wrap them in `` ``` ``.
|
||||
api-documenter doesn’t highlight examples if you don't wrap them in ` ``` `.
|
||||
|
||||
### Guidelines
|
||||
|
||||
- Only use one `@example` section
|
||||
- Use a single code block in it, no explanations
|
||||
- Wrap the code block in `` ```ts ... ``` `` (the `ts` modifier is important, api-documenter copies the `@example` section verbatim, and our documentation page might not highlight the vanilla `` ``` `` sections)
|
||||
- Wrap the code block in ` ```ts ... ``` ` (the `ts` modifier is important,
|
||||
api-documenter copies the `@example` section verbatim, and our documentation
|
||||
page might not highlight the vanilla ` ``` ` sections)
|
||||
- If you need to explain the code, use code comments
|
||||
|
||||
#### `@typeParam`
|
||||
|
||||
api-documenter doesn’t generate documentation for it, but IDEs might display it even if they don't have bespoke support for it.
|
||||
api-documenter doesn’t generate documentation for it, but IDEs might display it
|
||||
even if they don't have bespoke support for it.
|
||||
|
||||
#### `@link`
|
||||
|
||||
While in JSDoc you can specify paths relative to the current declaration, TSDoc requires everything to be specified relative to the entry point. That is, if `bar` is a member of `Foo`, and `Foo` is exported in the entry, you need to refer to `bar` as `Foo.bar`, even inside `Foo`.
|
||||
While in JSDoc you can specify paths relative to the current declaration, TSDoc
|
||||
requires everything to be specified relative to the entry point. That is, if
|
||||
`bar` is a member of `Foo`, and `Foo` is exported in the entry, you need to
|
||||
refer to `bar` as `Foo.bar`, even inside `Foo`.
|
||||
|
||||
JSDoc allows separating the link text from the link either with a space or using `|`. TSDoc only supports `|`, *and* you mustn’t have spaces around it. So for example `{@link MyClass | go here}` would be rendered incorrectly, whereas `{@link MyClass|go here}` would be correct.
|
||||
JSDoc allows separating the link text from the link either with a space or using
|
||||
`|`. TSDoc only supports `|`, _and_ you mustn’t have spaces around it. So for
|
||||
example `{@link MyClass | go here}` would be rendered incorrectly, whereas
|
||||
`{@link MyClass|go here}` would be correct.
|
||||
|
||||
#### `@param`
|
||||
|
||||
api-documenter won’t render the documentation for object properties, but document them anyway, IDEs do.
|
||||
api-documenter won’t render the documentation for object properties, but
|
||||
document them anyway, IDEs do.
|
||||
|
||||
Since documentation is only rendered for the object and not for its properties, make sure to include examples for these properties.
|
||||
Since documentation is only rendered for the object and not for its properties,
|
||||
make sure to include examples for these properties.
|
||||
|
||||
#### `@see`
|
||||
|
||||
While JSDoc attempts to hyperlink to anything after the `@see` tag, TSDoc requires an explicit `{@link}` tag tag to make hyperlinks.
|
||||
While JSDoc attempts to hyperlink to anything after the `@see` tag, TSDoc
|
||||
requires an explicit `{@link}` tag tag to make hyperlinks.
|
||||
|
||||
**Incorrect ❌**
|
||||
|
||||
|
|
@ -83,7 +102,7 @@ While JSDoc attempts to hyperlink to anything after the `@see` tag, TSDoc requir
|
|||
* @param url - the string to be parsed
|
||||
* @returns the parsed result
|
||||
*/
|
||||
function parseURL(url: string): ParsedUrl;
|
||||
function parseURL(url: string): ParsedUrl
|
||||
```
|
||||
|
||||
**Correct ✅**
|
||||
|
|
@ -97,5 +116,5 @@ function parseURL(url: string): ParsedUrl;
|
|||
* @param url - The string to be parsed
|
||||
* @returns The parsed result
|
||||
*/
|
||||
function parseURL(url: string): ParsedUrl;
|
||||
function parseURL(url: string): ParsedUrl
|
||||
```
|
||||
|
|
@ -1,3 +1,3 @@
|
|||
This is a bundle of @theatre/core and @theatre/studio packages.
|
||||
|
||||
See their licenses in their repo: https://github.com/ariaminaei/theatre
|
||||
See their licenses in their repo: https://github.com/theatre-js/theatre
|
||||
|
|
@ -63,7 +63,7 @@ const validateCommonOpts = (fnCallSignature: string, opts?: CommonOpts) => {
|
|||
*
|
||||
* // nesting
|
||||
* const foo = {bar: {baz: {quo: 0}}}
|
||||
* assert(sheet.object('some object', foo).bar.baz.quo === 0)
|
||||
* assert(sheet.object('some object', foo).value.bar.baz.quo === 0)
|
||||
*
|
||||
* // With additional options:
|
||||
* const position = t.compound(
|
||||
|
|
|
|||
Loading…
Reference in a new issue