Project Documentation Idea

[niccokunzmann]

Purpose

I want it to be easy to use my projects for other people. I do not want them to know abundance to download files.

Workflow Example in Abundance

I would like to be able to do generate documentation automatically for my abundance projects. As well as little examples on how it works. For that, a documentation molecule like the one for the README would be nice. E.g. the pipe adapter:

GitHub - niccokunzmann/pipe-adapter: Plug two pipes together with this adapter outside...

I would like to be able to create a documentation section with the pipe adapter like below:

Pipe Adapter

This is a configurable pipe adapter where you can specify the lengths and diameters to stick two pipes together.

Example Image

Customization

Here are the parameters (subset of input as input fields with description).

• Pipe 1: diameter of the hole

  mm

• Pipe 1: diameter of the outside

  mm

• Pipe 1: length of the adapter for that pipe

  mm

• Pipe 2: diameter of the hole

  mm

• Pipe 2: diameter of the outside

  mm

• Pipe 3: length of the adapter for that pipe

  mm

All are prefilled with the values I have in the project.

Then, there is a rotatable 3d image

That image is generated from a molecule.

Then, I have a choice of how to download this image.

Implementation

1. Since Abundance is automatically generating a README, abundance can also auto-generate a github pages page.
2. To start this off: I would like to have a molecule for 3d viewable output to which I can add parameters with their values. That could be a self-resizing canvas that is placed in an iframe:
   https://abundance.maslowcnc.com/niccokunzmann/pipe-adapter/api/canvas.html?id=moleculeid&pipe%20hole%201%20diameter=39
3. Second start-off: I would like to export the output of the project. That could also be addressed by a molecule (id=moleculeid) for a specific export.
   /pipe-adapter/api/spec → show the options of the parameters, the inputs, …
   /pipe-adapter/api/download?format=stl&filename=pipe-adapter - the format would be listed in the spec

Discussion: Positive side-effects for Abundace docs!

Having this kind of spec possibility from the start would allow creating a very different kind of documentation for Abundance that is interactive. Instead of having these pages with images and a “click this than that” description, Abundance documentation can actually showcase what is happening live and on the page of the molecules, actions, inputs, … and so on!

A third start for this is that you can embed the flow diagram area at the top or whole project page.
I mean, the possibilities are endless with this: You can even configure Discourse to allow an embed and definitely use that to make the documentation VERY useful!

Example iframe embed e.g. inside the documentation page for Abundance:

file:///home/nicco/Downloads/Bildschirmfoto%20am%202025-11-03%20um%2014.38.41.png

Since you can use existing projects as molecules - you can view the docs, fork it or embed it directly into your project

These are a lot of ideas, definitely doable. I would like to have documentation that is fun to write, view and use and that is itself easy to generate, view and re-use.

[bar]

I couldn’t agree more with the goals here.

A lot of this already exists in some form, but it may not be fully functional.

The built in “readme” atom type will generate a project readme exactly like that. The order is based on how close to the top left corner of the canvass you place the readme atom. The closer to the top left the higher up it will be in the doc. You can connect geometry to a readme input to add a diagram to the readme.

In terms of sharing projects you can use the share option at the top right (from the menu with three dots) to share a version of the project which doesn’t require logging in.

I think that it should already work to imbed in an iframe, but it would be nice to test and confirm that and maybe provide some example code.