Diagrams/etc for Threejs docs?

Discussion
1

I feel like some docs could benefit from visual diagrams, for example using toos like Mermaid.js, etc.

For example explaining BufferGeometryUtils.toCreasedNormals could have a diagram that shows what the angle is relative to two faces (you might think it accepts the angle between the faces, but that’s not true, however the wording sounds like it). It would be a simple 2D diagram: three dots with lines connecting them, and an angle marker.

Would PRs for this sort of thing be accepted?

2

At some point the API documentation might be generated from JSDoc (see RFC: Adopting JSDoc in three.js · GitHub). It would not be possible to retain the diagrams if we decide to go that route.

However, the manual already uses diagrams and would benefit from additional ones in certain pages. Even if the manual is converted to Markdown at some point (see Docs: Conversion from custom HTML generated documentation to regular Markdown generated documentation · Issue #27832 · mrdoob/three.js · GitHub), diagrams can be retained.

3

This should be possible, even with JSDoc. For example, I do the same in the glTF Transform documentation:

3 Likes
4

TS/JSDoc comments are markdown content which includes HTML. If we include a Custom Element (aka Web Component) inside a JSDoc comment, it can automatically come to life on a web page (while being invisible inside markdown-rendered tooltips in VS Code).

For example, here in the JSDoc comment of my MixedPlane class I have a small piece of HTML:

Here’s the implementation of <live-code>:

The Lume docs site has a <script> tag that imports the live-code module so that the element will be defined.

Here is the result:

https://docs.lume.io/api/meshes/MixedPlane

I also have a <code-mirror> element which is what <live-code> uses for the editor part:

Similarly, we could easily write a custom element like <mermaid-diagram> that wraps marmaid.js and use it in JSDoc comments like so:

<mermaid-diagram src="../some/diagram.uml"></mermaid-diagram>

The custom elements don’t require any build tooling, useful for this sort of thing. Lume’s doc site is a static website, no build step is needed except for one that transfers the JSDoc comments into markdown files (my own JSDoc parser in this case). The demo that <live-code> links to is simply a static HTML page:

https://docs.lume.io/examples/buttons-with-shadow/example.html

Managing the doc generator that will parse the markdown may be more complicated than the custom elements (diagrams, etc).

3 Likes