Tracker luma.gl docs and website improvements

[ibgreen]

We have a couple of major projects that are considering adopting luma.gl as a path to WebGPU, however the quality of the docs has come up as a concern.

This tracker task is open for users to add bullets about areas that could be improved

Docs - Sanity pass

• api guide shaderlayout - probably needs a pass to align with latest API
• api guide bindings - likely needs a pass
• engine Model docs have never been good - arguably the most important page in the docs
• gltf @luma.gl/gltf module, add basic docs - @ibgreen
• tutorials - port to v9 (currently marked as outdated) @ibgreen Tracker luma.gl docs and website improvements #2407

Website / Examples

• Website: (<DeviceTabs /> issue - Switching to WebGPU tab in one example should not persist when switching to non-WebGPU enabled example
• Examples: glfx - Port to WebGPU - P1 - TBD
• Examples: glfx - Restore example (so that we can test / showcase postprocessing modules) - P1 - TBD
• Examples: showcase/persistence - P0 - Use effects instead of custom shaders
• Examples: showcase/persistence - P0 - Port to WebGPU
• Examples: api/cubemap - P0 - Fix projection angles in WebGPU @ibgreen
• Examples: showcase/instancing - P0 - Implement cube picking on WebGPU @ibgreen
• Examples: showcase/instancing - P1 - Use dirlight module @ibgreen
• Examples: showcase/instancing - P0 - Port to WebGPU @ibgreen

Docs - Improvement areas

• gltf @luma.gl/gltf module, write good docs
• tutorials - refresh to make more useful (currently heavy focus on special features like shaderhooks and transforms)
• engine BufferTransform / TextureTransform docs - @donmccurdy

[PieceOfMeat]

I double this issue (if it means anything :) ). Not only tutorial docs are outdated, it's hard to find a working example on nearly any documentation page: most are very limited and sketchy, some are outdated or even plainly wrong. This renders (pun intended) documentation to be almost useless.

Issues I've run into just during the first hour of making a minimal "draw a triangle" app:

1. API Reference / @luma.gl/core / Overview page:
   "It is possible to register more than one device adapter to create an application that can work in both WebGL and WebGPU environments." - following code snippet adds only one adapter, and does it before even importing it from the package.

2. API Reference / @luma.gl/core / luma page
   This page contains correct version of the previous "add several adapters" code, hovewer, also contains several somewhat misleading snippets:

• "Register the WebGL backend, then create a WebGL2 context, auto creating a canvas" - following code does not auto create the canvas;
• "It is possible to register more than one device to create an application that can work in both WebGL and WebGPU environments." - following code creates exactly one device;

3. RenderPass API page contains beginRenderPass() call with parameters depthClearValue and stencilClearValue, while the actual luma.gl code expects them to be clearValue and clearStencil

Sorry for a large number of words, I just wanted to vent make my point - it seems that documentation could use a total recheck. Espesially up-to-date tutorials would greatly improve its usefulness.
In current state there's not a single example a new user like me could use as a starting point, and for API reference it's almost easier to check actual source code than to rely on a documentation.

[ibgreen]

@PieceOfMeat Thanks for the detailed input, an attempt to address it in #2424. Will need some additional work before we can update the actual website.

[filonik]

This line in the documentation is outdated:

luma.gl/docs/api-reference/engine/animation-loop.md

Line 29 in b63dfc6

animationLoop.start({canvas: 'my-canvas'});

I believe you have to use the createCanvasContext now:

luma.gl/docs/api-reference/core/luma.md

Line 19 in b63dfc6

Create a WebGL 2 context (throws if WebGL2 not supported)