Javascript Documentation

[msantic]

Hi everyone,

I just discovered the library yesterday, and I’m blown away by it. Incredible effort, and thank you for making it publicly available.

I’m particularly interested in using it on the web via JS bindings, but I found the lack of documentation challenging when trying to get started. I spent almost half a day gathering information and examples from various scattered sources before finally getting it to work.

As a web designer, I’d love to contribute to this project. I wanted to check with you all—did I miss something, or is there really no dedicated JavaScript documentation with an API reference, getting started tutorial, etc.?

So far, I’ve only found this: https://manifoldcad.org/docs/html/
I’m also aware of https://manifoldcad.org/, which is very helpful but doesn’t cover everything.

For example, on the official npm package page:

For example, this is what I've been working on, and I’d like to share the entire process: extruding the aluminum profile from an AutoCAD blueprint to a 3D object in Three.js.

Thank you

[pca006132]

Our javascript documentation is actually in our typescript files. The API documentation link is linking to the C++ API docs, and we probably forgot to update it in the previous link update PR. You can have a look at https://github.com/elalish/manifold/blob/master/bindings/wasm/manifold-encapsulated-types.d.ts. We should probably try to make it into a webpage and put it into our readme as well.

[msantic]

@pca006132, thanks! That looks very helpful and well-organized. My idea is to put it into a fancy docs web template, e.g., https://syntax.tailwindui.com. Let me know how to proceed since I'm new to this community and whether it's something worth considering.

[elalish]

Ah strange - the npm page supposedly comes from our main README, but I guess it only gets updated when we push a release? The links aren't broken here: https://github.com/elalish/manifold?tab=readme-ov-file#manifold

Yes, help with documentation is always appreciated! I put some effort into our Doxygen pages, but it is just the C++ API. We have stubs for Python and TS declarations for our WASM, but making them more accessible would be great. If you know a fairly automatic system for keeping such a page up to date, that would be fantastic.

[pca006132]

I think the link in bindings/wasm/readme.md is indeed broken

[msantic]

Yeah, it seeams the README.md updates only on a new release (Source: https://docs.npmjs.com/about-package-readme-files).

Regarding automatic docs generation, there's a popular tool called Typedoc. I've tested it out, and it outputs a fairly good website by default without any customization.

You can test it yourself by typing:

npm i -g typedoc

and then in the bindings/wasm directory, run:

typedoc manifold-encapsulated-types.d.ts

I put the output on this temporary website so you can have a look: https://copper-jade-41.tiiny.site

To customize it, we can just create a main config file typedoc.json and new directory 'documents' to include extra markdown documents. For example:

{
  "entryPoints": ["manifold-encapsulated-types.d.ts"],
  "projectDocuments": ["documents/*.md"]
}

and then just run the following command to generate the documentation (outputs in the ./docs directory):

typedoc

It even allows output to JSON, so we can generate the look and feel of the API reference the way we want. However, this, of course, requires more work.

typedoc --json output.json manifold-encapsulated-types.d.ts

Next steps

In my opinion, it would be a great start to just publish this out-of-the-box Typedoc website. In the long term, we can create a custom theme to have a more appealing look and include more interactive code samples and tutorials.

[elalish]

In my opinion, it would be a great start to just publish this out-of-the-box Typedoc website. In the long term, we can create a custom theme to have a more appealing look and include more interactive code samples and tutorials.

Yes, I wholeheartedly agree! You temp website looks good, though for some reason it picked up descriptions for the Manifold part of the API, but not for Mesh - maybe we need to tweak the format of our comments?

Would you like to make a PR to add this to our Github Pages deployment?