docs: add complete build123d + visualization demo via ocp_vscode "standalone" mode

[jdegenstein]

Now that ocp_vscode supports use in a regular browser (and not strictly bound with VSCode), it is much easier to explain how one could simply:

1. pip install build123d ocp_vscode
2. execute python -m ocp_vscode
3. open http://127.0.0.1:3939/viewer in a suitable browser
4. execute a python file with necessary build123d and ocp_vscode imports and show statement

As a way to get users "up and running quickly" I propose something similar to the above is added to the build123d docs (with appropriate links/caveats back to the ocp_vscode repo/docs). Further I propose that a screenshot is added to show what this could look like (maybe with vim + chrome, or something similar).

[gumyr]

+1

[jdegenstein]

Screenshot for the docs [using Ubuntu 20.04, gedit, gnome-terminal, ipython and firefox]:

[gumyr]

Nice

[codingandmore]

Yes nice! I suggest to consider a few more things:

• If you follow the installation instructions there is no hint that you have to pip install ocp_vscode. For me it was confusing to see that the show()/show_all() functions can't be resolved. And I had no idea how to import them (you can find it much later somewhere). I understand that this is not part of build123d itself but every user needs to visualize his models somehow.
• Beside the standalone mode there is an option "Move to new Window" in VSCode. Not sure that everyone will find this immediately. It is useful if you still want to work within VSCode but with limited screen space, like a laptop. If you assign a keyboard shortcut to toggle between the windows it can be quite convenient. This still supports debug mode. Yes I know this is not a VSCode documentation....

Would it make sense to start a discussion what else could get "users up and running quickly"?

• if people have a programming background but not necessary a Python one explain environments, pip?
• Provide a VSCode profile template installing everything needed for build123d
• Provide an app template or example for frequently used functions in a command line using argparse (e.g. python mymodel.py --export stl , python mymodel --show , ...
  Probably there are many more ideas. Might also be placed elsewhere in a wiki or so.

[gumyr]

Here is a screen grab from the installation instructions:

How can we make this more clear?

If one follows the link to ocp_vscode, it describes how it can be installed in vscode and install both build123d and cadquery if you like.

Should pip be a hyperlink to the pip documentation? Would that be sufficient?

The full power of python is available to users in their scripts, how would you propose that argument parsing be done in a more built-in way?

[codingandmore]

I am not the only one who struggled at this point, see here.

Suggestion:

The recommended method for most users to install build123d is:

pip install build123d

buiild123d is a Python library without any user interface. In most cases you want to visualize your models however. A commonly used tool for this ocp-vscode. It can display models in VSCode or standalone in a web browser. To add this tool to your environment call:

pip install ocp_vscode

For an integration with VSCode you also need the extension "OCP CAD Viewer" from the marketplace.

Box with Note: As an alternative you can install only the VSCode extension. It has the ability to install all required libraries.

You can find more similar tools here

and in the first Note from Introductory Examples under 1. add:
from ocp_vscode import show, show_all

I need to think more about the argparse thing and come up with a more concrete example. I don't think it has to be built-in. But everybody sooner or later needs to perform more than one function on his script. Giving some guidance how you can accomplish this with code could be helpful for someone coming from a "GUI-CAD" background. Maybe there are better ways than command line arguments (Jupiter notebooks?, a button to export in the viewer?) Anyway this belongs to another issue/discussion.

[Jojain]

The thing is before the standalone version of ocp_vscode, the recommended way was to install the extension in the VSCode market place and install the ocp_vscode python package from the extension.

Since ocp_vscode is also a project that is evolving build123d cannot keep up the documentation up to date easily.
I'm for more explicitly stating that there is no viewing capabilities in build123d and if one wants one then we could link ocp_vscode but more specific informations should not be written in the build123d docs as they can quickly become out of date.

[codingandmore]

Understood, but keep the documentation consistent. This means that the provided sample code should work after following the installation instructions. Currently the doc states the recommended way is to use pip (which is good). It should mention how to make the show() call working. If it only works after following the instructions from a provided link, fine. But I also do not see that the ocp_vscode documentation mentions anywhere in the three provided options that you can use pip to install it. This is a bit unfortunate as this would be my preferred way (and I assume many others) to set everything up. The cool thing about build123d is that it is now so easy to setup if you have basic Python knowledge. Two pip commnands...done. Just tell us users that it is not more than this.

[gumyr]

This is an open-source project that welcomes pull-requests so if you have improvements to make to the docs then go ahead. Like most open-source projects there are only a few people keeping the lights on so we can't do everything at once.

[mortisj]

I would say that ocp-vscode is just one way to create and visualize designs, and it would be easy to be turned off by build123d if that was perceived as the only way to do it. Personally I prefer a simpler approach: command line emacs to write the code and Mayo (https://dev.opencascade.org/project/mayo) to display the resulting exported step file. Mayo has auto-reloading so it all works quite smoothly. Cheers.