chore: add docs (#223)

.github/workflows/deploy-docs.yml

@@ -0,0 +1,66 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    paths:
+      - "docs/**"
+    branches:
+      - main
+      - chore/docs
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  build:
+    name: Build Docusaurus
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # As we use typedoc we need to install the node_modules in the package as well
+      - name: Install package/ deps
+        working-directory: package
+        run: |
+          corepack enable
+          yes | yarn install
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: docs
+
+      - name: Build website
+        run: yarn build
+        working-directory: docs
+
+      - name: Upload Build Artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test-deploy-docs.yml

@@ -0,0 +1,39 @@
+name: Test deployment
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+
+jobs:
+  test-deploy:
+    name: Test deployment
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # As we use typedoc we need to install the node_modules in the package as well
+      - name: Install package/ deps
+        working-directory: package
+        run: |
+          corepack enable
+          yes | yarn install
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: yarn
+          cache-dependency-path: docs
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+        working-directory: docs
+      - name: Test build website
+        run: yarn build
+        working-directory: docs

README.md

@@ -12,7 +12,12 @@
 
 react-native-filament is a powerful 3D rendering engine for React Native. It features:
 
-* ⚡ List features here with emojis
+* ⚡ Native GPU accelerated rendering using [filament](https://github.com/google/filament)
+* 🏎️ Uses Metal on iOS and OpenGL/Vulkan on android
+* 📹 Rendering happens on a separate thread, nothing blocks the JS thread
+* 🏀 Comes with a physics engine as well, wrapping [bullet3](https://github.com/bulletphysics/bullet3)
+* 📦 Easy to use declarative API
+* ✅ Supports old and new arch
 
 ### Installation
 
@@ -34,12 +39,12 @@ npm i react-native-worklets-core
 cd ios && pod install
 ```
 
-..and get started by [loading your model](https://docs.go.here)!
+..and get started by [loading your model (docs)](https://margelo.github.io/react-native-filament/docs/guides)!
 
 ### Example
 
 ```tsx
-import { FilamentScene, FilamentView, Model, Camera } from 'react-native-filament'
+import { FilamentScene, FilamentView, Model, Camera, DefaultLight } from 'react-native-filament'
 
 function App() {
   return (
@@ -48,10 +53,14 @@ function App() {
         style={{ width: 100, height: 100 }}
         model={model}
       >
-        // Render with the default camera:
+
+        {/* Render with the default camera and light: */}
         <Camera />
-        // Add a model to the scene (only glb supported yet):
+        <DefaultLight >
+
+        {/* Add a model to the scene (only glb supported yet): */}
         <Model source={require('./duck.glb')}>
+
       </FilamentView>
     </FilamentScene>
   )
@@ -60,6 +69,17 @@ function App() {
 
 > See the [example](./package/example/) app
 
+
+### Comparison with other libraries
+
+One library to render 3D content is [expo-gl](https://docs.expo.dev/versions/latest/sdk/gl-view) usually used together with [expo-three](https://www.npmjs.com/package/expo-three). react-native-filament has a few advantages over expo-gl:
+
+- Supports using `glb` files out of the box
+- On iOS react-native-filament uses Metal, where expo-gl is using the [deprecated OpenGL ES](https://developer.apple.com/documentation/opengles) apple framework
+- The rendering happens on the JS thread for `expo-three`, where react-native-filament uses a separate thread (and filament processes the rendering commands in a pool of different threads)
+- filament is battle tested and react-native-filament is used in production apps with millions of users already, proven to be highly stable
+
+
 ### Contributing
 
 We welcome contributions to react-native-filament! 🎉
@@ -98,8 +118,13 @@ If you need help with integrating react-native-filament in your app or have addi
 * 🐦 [**Follow us on Twitter**](https://twitter.com/margelo) for updates
 * 💬 [**Join the Margelo Community Discord**](https://discord.gg/6CSHz2qAvA) for chatting about react-native-filament
 
-#### Attributions
+#### Attributions & thanks
+
+A big thanks to [filament](https://github.com/google/filament) for building such a great rendering engine!
 
 The example app in this project uses several free assets:
-- <a href="https://www.freepik.com/free-ai-image/space-travel-collage-design_94964745.htm#fromView=search&page=1&position=1&uuid=cf66f9c3-2d56-4228-a3cf-de7c07d418fb">Image by freepik</a>
+- Image by <a href="https://www.freepik.com/free-ai-image/space-travel-collage-design_94964745.htm#fromView=search&page=1&position=1&uuid=cf66f9c3-2d56-4228-a3cf-de7c07d418fb">freepik</a>
+- Image by <a href="https://www.freepik.com/free-psd/3d-icon-product-management_44990845.htm#fromView=search&page=2&position=0&uuid=691aae54-efdf-451c-9112-0ff373e761e7">Freepik</a>
+- Image by <a href="https://www.freepik.com/free-psd/3d-collection-with-hands-holding-smartphone_13678985.htm#fromView=search&page=1&position=3&uuid=7761a685-d1b6-4202-8505-9a872775cbbb">Freepik</a>
+- Michelle by [mixamo](https://www.mixamo.com/#/?page=2&type=Character)
 - "Buster Drone" (https://skfb.ly/TBnX) by LaVADraGoN is licensed under Creative Commons Attribution-NonCommercial (http://creativecommons.org/licenses/by-nc/4.0/).

docs/.gitignore

@@ -0,0 +1,21 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+docs/api
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/guides/ANIMATOR.mdx

@@ -0,0 +1,8 @@
+---
+id: animator
+title: Animator
+sidebar_label: Animator
+slug: /guides/animator
+---
+
+Documentation is added soon!

docs/docs/guides/ASSET_LOADING.mdx

@@ -0,0 +1,86 @@
+---
+id: asset-loading
+title: Asset loading
+sidebar_label: Asset loading
+slug: /guides/asset-loading
+---
+
+# Load from everywhere
+
+You can load assets from basically any source that comes to mind. Assets refer to anything that is not code, like 3D models, textures, material shaders, etc.
+There are many components which accept a `source` prop, for example the `<Model source={...} />` component. For these components, the `source` prop can be of the following types:
+
+## 🧑‍💻 From assets in your project / metro
+
+Files that live next to your code. For this to work make sure you followed the metro bundle configuration in the [Getting Started](/docs/guides#configure-metro) guide.
+
+```tsx
+import { Model } from 'react-native-filament';
+import BusterDrone from './BusterDrone.glb';
+
+<Model source={BusterDrone} />
+```
+
+:::info
+Currently only loading `.glb` files is supported. You can convert any other 3D models (gltf, obj, FBX, etc) to .glb using blender or online converter tools.
+:::
+
+### Debug
+
+In debug mode this will get the file from the metro bundler server, running on your machine. That means a network requests is made for example to `http://localhost:8081/assets/BusterDrone.glb`.
+
+:::warning
+If your files are big loading over network can introduce some delay until the file is loaded and displayed. Make sure to profile your app in release!
+:::
+
+### Release
+
+React Natives default behaviour is to bundle all assets into the app binary. This means that the file is not loaded over network but from the app binary itself, which is faster than in debug over network.
+
+:::warning
+If you put your assets into other directories than the default `/assets` dir, you need to specify the path to the assets in your `react-native.config.js` file:
+```js
+module.exports = {
+    assets: [
+        './app/assets/3d/assets',
+    ],
+}
+```
+
+See the [React Native documentation](https://github.com/react-native-community/cli/blob/main/docs/projects.md#projectandroidassets) for more information.
+:::
+
+## 📦 From native asset / bundle resources
+
+You can place assets directly in your native project and load them from there. This way the will load very fast, even in debug mode:
+
+- 🤖 android: place assets under `android/app/main/assets/BusterDrone.glb`
+- 🍏 ios: place assets under `ios/assets/BusterDrone.glb` and import them in your XCode project
+
+Then, you can simply load them by providing the name to the asset:
+
+```tsx
+<Model source={{ uri: "BusterDrone.glb" }}>
+
+// If the asset is in a subdirectory:
+<Model source={{ uri: "subdir/BusterDrone.glb" }}>
+```
+
+
+## 📁 From a local file path
+
+Files can also be loaded from the file directory on the device. This is useful if you load models from the web and want to cache them, by downloading them to your app's file directory.
+Note that if you want to open files from a public directory, such as the user's Downloads you might need to ask for permissions first.
+
+```tsx
+<Model source={{ uri: `file://${path}` }}>
+```
+
+
+## 🌐 From web urls
+
+You can also load assets from the web. This is useful if you want to load assets dynamically from a server or a CDN.
+
+```tsx
+<Model source={{ uri: "https://example.com/BusterDrone.glb" }}>
+```