diff --git a/.gitignore b/.gitignore index 53b2e0360d..e670e08430 100644 --- a/.gitignore +++ b/.gitignore @@ -106,4 +106,4 @@ src/ifcopenshell-python/ifcopenshell/ifcopenshell_wrapper.py src/bonsai/bonsai/bim/schema/Brick.ttl bonsaiDecoratorForLoads.code-workspace -dev_environment.bat + diff --git a/src/bonsai/docs/index.rst b/src/bonsai/docs/index.rst index 334fb67809..0e4d91d664 100644 --- a/src/bonsai/docs/index.rst +++ b/src/bonsai/docs/index.rst @@ -39,12 +39,13 @@ and data-rich OpenBIM with Blender :) .. toctree:: :hidden: :caption: Quickstart - :maxdepth: 1 + :maxdepth: 2 quickstart/introduction_to_bim quickstart/installation quickstart/explore_model quickstart/create_model + quickstart/ide/index quickstart/next_steps .. toctree:: diff --git a/src/bonsai/docs/quickstart/ide/bonsai_style_annotation.svg b/src/bonsai/docs/quickstart/ide/bonsai_style_annotation.svg new file mode 100644 index 0000000000..2d0c39770f --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/bonsai_style_annotation.svg @@ -0,0 +1,180 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/bonsai/docs/quickstart/ide/images/GitHubUser.png b/src/bonsai/docs/quickstart/ide/images/GitHubUser.png new file mode 100644 index 0000000000..e98680b51c Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/GitHubUser.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-and-blender.png b/src/bonsai/docs/quickstart/ide/images/VSCode-and-blender.png new file mode 100644 index 0000000000..c2f4a37878 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-and-blender.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-2-windows.png b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-2-windows.png new file mode 100644 index 0000000000..17cdddf680 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-2-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-linux.png b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-linux.png new file mode 100644 index 0000000000..44ff754d61 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-windows.png b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-windows.png new file mode 100644 index 0000000000..f15cd34b09 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-additional-arguments-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-blender-extension-settings.png b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-extension-settings.png new file mode 100644 index 0000000000..1b699d0e62 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-extension-settings.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-blender-extension.png b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-extension.png new file mode 100644 index 0000000000..4d1f1be465 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-extension.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-blender-start.png b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-start.png new file mode 100644 index 0000000000..93fa2c4c8e Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-blender-start.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-extensions.png b/src/bonsai/docs/quickstart/ide/images/VSCode-extensions.png new file mode 100644 index 0000000000..2b8981fb74 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-extensions.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-python-version-linux.png b/src/bonsai/docs/quickstart/ide/images/VSCode-python-version-linux.png new file mode 100644 index 0000000000..68879fc5b7 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-python-version-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/VSCode-python-version-windows.png b/src/bonsai/docs/quickstart/ide/images/VSCode-python-version-windows.png new file mode 100644 index 0000000000..6460bd0aca Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/VSCode-python-version-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/blender-installation-1.png b/src/bonsai/docs/quickstart/ide/images/blender-installation-1.png new file mode 100644 index 0000000000..700b5bbfcd Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/blender-installation-1.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/blender-installation-2.png b/src/bonsai/docs/quickstart/ide/images/blender-installation-2.png new file mode 100644 index 0000000000..786c765082 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/blender-installation-2.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/blender-python-version.png b/src/bonsai/docs/quickstart/ide/images/blender-python-version.png new file mode 100644 index 0000000000..76fd338ac7 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/blender-python-version.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/blender_development_addons.png b/src/bonsai/docs/quickstart/ide/images/blender_development_addons.png new file mode 100644 index 0000000000..03047f1d71 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/blender_development_addons.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/blender_experimental_debugging.png b/src/bonsai/docs/quickstart/ide/images/blender_experimental_debugging.png new file mode 100644 index 0000000000..e103febd75 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/blender_experimental_debugging.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/bonsai-doc-server.png b/src/bonsai/docs/quickstart/ide/images/bonsai-doc-server.png new file mode 100644 index 0000000000..49a9d74a69 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/bonsai-doc-server.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/bonsai-layout2.png b/src/bonsai/docs/quickstart/ide/images/bonsai-layout2.png new file mode 100644 index 0000000000..8e4c7d83dc Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/bonsai-layout2.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/bonsai_debug.png b/src/bonsai/docs/quickstart/ide/images/bonsai_debug.png new file mode 100644 index 0000000000..f5c740059d Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/bonsai_debug.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/break-point-stop.png b/src/bonsai/docs/quickstart/ide/images/break-point-stop.png new file mode 100644 index 0000000000..c491707d55 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/break-point-stop.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/break-point.png b/src/bonsai/docs/quickstart/ide/images/break-point.png new file mode 100644 index 0000000000..1f7371a637 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/break-point.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/check-fork.png b/src/bonsai/docs/quickstart/ide/images/check-fork.png new file mode 100644 index 0000000000..08a923a78e Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/check-fork.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/checkout_pull_request_vscode.png b/src/bonsai/docs/quickstart/ide/images/checkout_pull_request_vscode.png new file mode 100644 index 0000000000..c6991299d8 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/checkout_pull_request_vscode.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/cloned-repo.png b/src/bonsai/docs/quickstart/ide/images/cloned-repo.png new file mode 100644 index 0000000000..f33925bac1 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/cloned-repo.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/cloning-from-github.png b/src/bonsai/docs/quickstart/ide/images/cloning-from-github.png new file mode 100644 index 0000000000..8a1fa8c195 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/cloning-from-github.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/commit-changes-linux.png b/src/bonsai/docs/quickstart/ide/images/commit-changes-linux.png new file mode 100644 index 0000000000..c537cc3212 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/commit-changes-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/commit-changes-windows.png b/src/bonsai/docs/quickstart/ide/images/commit-changes-windows.png new file mode 100644 index 0000000000..3390d59592 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/commit-changes-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/compare-and-pull-request.png b/src/bonsai/docs/quickstart/ide/images/compare-and-pull-request.png new file mode 100644 index 0000000000..5b4a780030 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/compare-and-pull-request.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/create-branch.png b/src/bonsai/docs/quickstart/ide/images/create-branch.png new file mode 100644 index 0000000000..441f6f8abe Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/create-branch.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/create-user.png b/src/bonsai/docs/quickstart/ide/images/create-user.png new file mode 100644 index 0000000000..590261ea75 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/create-user.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/dev-environment-sh-executed.png b/src/bonsai/docs/quickstart/ide/images/dev-environment-sh-executed.png new file mode 100644 index 0000000000..1bcb042e51 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/dev-environment-sh-executed.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/dev-environment-sh.png b/src/bonsai/docs/quickstart/ide/images/dev-environment-sh.png new file mode 100644 index 0000000000..11f35fb9e4 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/dev-environment-sh.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/doc-pip-furo.png b/src/bonsai/docs/quickstart/ide/images/doc-pip-furo.png new file mode 100644 index 0000000000..1635c245fa Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/doc-pip-furo.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/doc-server-running.png b/src/bonsai/docs/quickstart/ide/images/doc-server-running.png new file mode 100644 index 0000000000..06e63490db Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/doc-server-running.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/edit_source.png b/src/bonsai/docs/quickstart/ide/images/edit_source.png new file mode 100644 index 0000000000..ffaa8ebd3d Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/edit_source.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/enable-developer-extras.png b/src/bonsai/docs/quickstart/ide/images/enable-developer-extras.png new file mode 100644 index 0000000000..c49f5f66c7 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/enable-developer-extras.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/environment-variables.png b/src/bonsai/docs/quickstart/ide/images/environment-variables.png new file mode 100644 index 0000000000..183081825c Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/environment-variables.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/fork-bonsai.png b/src/bonsai/docs/quickstart/ide/images/fork-bonsai.png new file mode 100644 index 0000000000..abfa850b31 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/fork-bonsai.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/forked-bonsai.png b/src/bonsai/docs/quickstart/ide/images/forked-bonsai.png new file mode 100644 index 0000000000..0ccfa5020e Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/forked-bonsai.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/git-user-email-linux.png b/src/bonsai/docs/quickstart/ide/images/git-user-email-linux.png new file mode 100644 index 0000000000..4f88c06325 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/git-user-email-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/git-user-email-windows.png b/src/bonsai/docs/quickstart/ide/images/git-user-email-windows.png new file mode 100644 index 0000000000..6c39fb3ab0 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/git-user-email-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/inkscape-annotation-template.png b/src/bonsai/docs/quickstart/ide/images/inkscape-annotation-template.png new file mode 100644 index 0000000000..2b2c2b255f Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/inkscape-annotation-template.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/inkscape-scaling-outline.png b/src/bonsai/docs/quickstart/ide/images/inkscape-scaling-outline.png new file mode 100644 index 0000000000..83c858f35a Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/inkscape-scaling-outline.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-bpy-fake-linux.png b/src/bonsai/docs/quickstart/ide/images/install-bpy-fake-linux.png new file mode 100644 index 0000000000..f7f50c83fd Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-bpy-fake-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-bpy-fake-windows.png b/src/bonsai/docs/quickstart/ide/images/install-bpy-fake-windows.png new file mode 100644 index 0000000000..ba3e3f8767 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-bpy-fake-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-python-1.png b/src/bonsai/docs/quickstart/ide/images/install-python-1.png new file mode 100644 index 0000000000..2a9e4d9555 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-python-1.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-python-2.png b/src/bonsai/docs/quickstart/ide/images/install-python-2.png new file mode 100644 index 0000000000..d8d671f9ad Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-python-2.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-python-3.png b/src/bonsai/docs/quickstart/ide/images/install-python-3.png new file mode 100644 index 0000000000..033b363d30 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-python-3.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-python-4.png b/src/bonsai/docs/quickstart/ide/images/install-python-4.png new file mode 100644 index 0000000000..dcacaf9be7 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-python-4.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-python-5.png b/src/bonsai/docs/quickstart/ide/images/install-python-5.png new file mode 100644 index 0000000000..53e21070de Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-python-5.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-python-6.png b/src/bonsai/docs/quickstart/ide/images/install-python-6.png new file mode 100644 index 0000000000..9fcc6d3fd2 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-python-6.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/install-vscode.png b/src/bonsai/docs/quickstart/ide/images/install-vscode.png new file mode 100644 index 0000000000..9174c3088e Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/install-vscode.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/just-my-code-false.png b/src/bonsai/docs/quickstart/ide/images/just-my-code-false.png new file mode 100644 index 0000000000..0fe114c178 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/just-my-code-false.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/launch-linux-jason.png b/src/bonsai/docs/quickstart/ide/images/launch-linux-jason.png new file mode 100644 index 0000000000..9950cfb4f0 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/launch-linux-jason.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/launch-terminal.png b/src/bonsai/docs/quickstart/ide/images/launch-terminal.png new file mode 100644 index 0000000000..e4d6bc2fbf Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/launch-terminal.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/launch-windows-jason.png b/src/bonsai/docs/quickstart/ide/images/launch-windows-jason.png new file mode 100644 index 0000000000..de65fd5a13 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/launch-windows-jason.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/make-changes-linux.png b/src/bonsai/docs/quickstart/ide/images/make-changes-linux.png new file mode 100644 index 0000000000..9df371c551 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/make-changes-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/make-changes-windows.png b/src/bonsai/docs/quickstart/ide/images/make-changes-windows.png new file mode 100644 index 0000000000..386bd7a04a Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/make-changes-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/marked_code.png b/src/bonsai/docs/quickstart/ide/images/marked_code.png new file mode 100644 index 0000000000..8bf74060a6 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/marked_code.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/new-branch-in-private-github.png b/src/bonsai/docs/quickstart/ide/images/new-branch-in-private-github.png new file mode 100644 index 0000000000..22d6f47384 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/new-branch-in-private-github.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/new-branch-local.png b/src/bonsai/docs/quickstart/ide/images/new-branch-local.png new file mode 100644 index 0000000000..162b5bc820 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/new-branch-local.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/new-branch-publish-to-private-github.png b/src/bonsai/docs/quickstart/ide/images/new-branch-publish-to-private-github.png new file mode 100644 index 0000000000..ec8b049abc Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/new-branch-publish-to-private-github.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/print-to-console.png b/src/bonsai/docs/quickstart/ide/images/print-to-console.png new file mode 100644 index 0000000000..26fa712033 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/print-to-console.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/private-fork-new-branch-updated-linux.png b/src/bonsai/docs/quickstart/ide/images/private-fork-new-branch-updated-linux.png new file mode 100644 index 0000000000..ac9f52c0ac Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/private-fork-new-branch-updated-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/private-fork-new-branch-updated-windows.png b/src/bonsai/docs/quickstart/ide/images/private-fork-new-branch-updated-windows.png new file mode 100644 index 0000000000..f1bf77a19d Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/private-fork-new-branch-updated-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/pull-changes.png b/src/bonsai/docs/quickstart/ide/images/pull-changes.png new file mode 100644 index 0000000000..db7fcc3dda Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/pull-changes.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/pull-request-linux.png b/src/bonsai/docs/quickstart/ide/images/pull-request-linux.png new file mode 100644 index 0000000000..63c7ea6d2d Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/pull-request-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/pull-request-windows.png b/src/bonsai/docs/quickstart/ide/images/pull-request-windows.png new file mode 100644 index 0000000000..bac995877c Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/pull-request-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/pull_request_see.png b/src/bonsai/docs/quickstart/ide/images/pull_request_see.png new file mode 100644 index 0000000000..3bed5b6419 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/pull_request_see.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/push-to-private-fork-new-branch.png b/src/bonsai/docs/quickstart/ide/images/push-to-private-fork-new-branch.png new file mode 100644 index 0000000000..fc90c04ad8 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/push-to-private-fork-new-branch.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/python-downloads.png b/src/bonsai/docs/quickstart/ide/images/python-downloads.png new file mode 100644 index 0000000000..6289916a51 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/python-downloads.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/python-version.png b/src/bonsai/docs/quickstart/ide/images/python-version.png new file mode 100644 index 0000000000..5cfbb2d2ec Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/python-version.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/rebase_branch.png b/src/bonsai/docs/quickstart/ide/images/rebase_branch.png new file mode 100644 index 0000000000..348573f32b Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/rebase_branch.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/restart-blender.png b/src/bonsai/docs/quickstart/ide/images/restart-blender.png new file mode 100644 index 0000000000..cb18c24a82 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/restart-blender.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/run-as-administrator.png b/src/bonsai/docs/quickstart/ide/images/run-as-administrator.png new file mode 100644 index 0000000000..560c8bcf8b Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/run-as-administrator.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/running-dev_environment-bat.png b/src/bonsai/docs/quickstart/ide/images/running-dev_environment-bat.png new file mode 100644 index 0000000000..429404547c Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/running-dev_environment-bat.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/script-blender-vscode-2.png b/src/bonsai/docs/quickstart/ide/images/script-blender-vscode-2.png new file mode 100644 index 0000000000..d78038f5f3 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/script-blender-vscode-2.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/script-blender-vscode.png b/src/bonsai/docs/quickstart/ide/images/script-blender-vscode.png new file mode 100644 index 0000000000..4d043f7f7b Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/script-blender-vscode.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/scripting_ui_code.png b/src/bonsai/docs/quickstart/ide/images/scripting_ui_code.png new file mode 100644 index 0000000000..6a3297f1f4 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/scripting_ui_code.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/selecting-forked-repo.png b/src/bonsai/docs/quickstart/ide/images/selecting-forked-repo.png new file mode 100644 index 0000000000..c43a32ab29 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/selecting-forked-repo.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/staging-prior-commit.png b/src/bonsai/docs/quickstart/ide/images/staging-prior-commit.png new file mode 100644 index 0000000000..eef3c21fca Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/staging-prior-commit.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/step-over-linux.png b/src/bonsai/docs/quickstart/ide/images/step-over-linux.png new file mode 100644 index 0000000000..f6ffd6fa9a Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/step-over-linux.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/step-over.png b/src/bonsai/docs/quickstart/ide/images/step-over.png new file mode 100644 index 0000000000..150e83d5f6 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/step-over.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/sync-fork.png b/src/bonsai/docs/quickstart/ide/images/sync-fork.png new file mode 100644 index 0000000000..18fb5bee3c Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/sync-fork.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/tasks-linux-jason.png b/src/bonsai/docs/quickstart/ide/images/tasks-linux-jason.png new file mode 100644 index 0000000000..46ef531b84 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/tasks-linux-jason.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/tasks-windows-jason.png b/src/bonsai/docs/quickstart/ide/images/tasks-windows-jason.png new file mode 100644 index 0000000000..b1dcda5d87 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/tasks-windows-jason.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/terminal-integrated-windows.png b/src/bonsai/docs/quickstart/ide/images/terminal-integrated-windows.png new file mode 100644 index 0000000000..be7b501542 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/terminal-integrated-windows.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/trigger-breakpoint.png b/src/bonsai/docs/quickstart/ide/images/trigger-breakpoint.png new file mode 100644 index 0000000000..b826b7ea0e Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/trigger-breakpoint.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/vscode_search_in_files.png b/src/bonsai/docs/quickstart/ide/images/vscode_search_in_files.png new file mode 100644 index 0000000000..f13b6395b0 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/vscode_search_in_files.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/vscode_search_results.png b/src/bonsai/docs/quickstart/ide/images/vscode_search_results.png new file mode 100644 index 0000000000..f895473dbf Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/vscode_search_results.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/win-add-user.png b/src/bonsai/docs/quickstart/ide/images/win-add-user.png new file mode 100644 index 0000000000..b7aacb37c6 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/win-add-user.png differ diff --git a/src/bonsai/docs/quickstart/ide/images/windows-path.png b/src/bonsai/docs/quickstart/ide/images/windows-path.png new file mode 100644 index 0000000000..ad649aeb58 Binary files /dev/null and b/src/bonsai/docs/quickstart/ide/images/windows-path.png differ diff --git a/src/bonsai/docs/quickstart/ide/index.rst b/src/bonsai/docs/quickstart/ide/index.rst new file mode 100644 index 0000000000..4e279cba8f --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/index.rst @@ -0,0 +1,15 @@ +Exploring Bonsai Sourcecode +=========== + +Here are quickstarts to help contribute to Bonsai either by troubleshooting or proposing new features for either the srouce code or the documentation. + +.. container:: global-index-toc + + .. toctree:: + :hidden: + :maxdepth: 2 + + linux_ide + windows_ide + macos_ide + diff --git a/src/bonsai/docs/quickstart/ide/linux/dev_environment.sh b/src/bonsai/docs/quickstart/ide/linux/dev_environment.sh new file mode 100644 index 0000000000..47bc7c9a2f --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/linux/dev_environment.sh @@ -0,0 +1,94 @@ +#!/bin/bash +# Please update REPO_PATH and BLENDER_PATH in the script below. +# Default BLENDER_PATH on Mac: "/Users/$USER/Library/Application Support/Blender/4.4" +# Default BLENDER_PATH on Linux: "$HOME/.config/blender/4.4" +# REPO_PATH="/path/to/where/your/git/repository/is/cloned/IfcOpenShell" +set -e +REPO_PATH="$HOME/bonsaiDevel/IfcOpenShell" +BLENDER_PATH="$HOME/.config/blender/4.4" +PACKAGE_PATH="${BLENDER_PATH}/extensions/.local/lib/python3.11/site-packages" +# If you are installing offline, use this instead: +# BONSAI_PATH="${BLENDER_PATH}/extensions/user_default/bonsai" +BONSAI_PATH="${BLENDER_PATH}/extensions/raw_githubusercontent_com/bonsai" + +# Changing to the Git repository directory +cd "${REPO_PATH}" + + +# Add files that need to be ignored in push to GiHub (.gitignore). Namely *.so files are very big and do not need to be pushed +FILE=".gitignore" +STRING="*.so" + +# Check if the file exists and contains the string +if [ ! -f "$FILE" ] || ! grep -qxF "$STRING" "$FILE"; then + echo "$STRING" >> "$FILE" + echo "Added '$STRING' to $FILE" +else + echo "'$STRING' already exists in $FILE" +fi + + + +# Print summary of PATHs +echo "Please review if the following is right:" +echo "PWD: ${PWD}" +echo "REPO PATH (...../IfcOpenshell): ${REPO_PATH}" +echo "BLENDER PATH: ${BLENDER_PATH}" +echo "PACKAGE PATH (...../etensions/.local/lib/python3.11/site-packages): ${PACKAGE_PATH}" +echo "BONSAI PATH (...../extensions/raw_githubusercontent_com/bonsai): ${BONSAI_PATH}" +read -p "Press any key to START or CTRL-C to stop ..." + +# Copy over compiled IfcOpenShell files +for src_file in "${PACKAGE_PATH}/ifcopenshell/"*_wrapper*; do + dest_file="${PWD}/src/ifcopenshell-python/ifcopenshell/$(basename "$src_file")" + # Only copy if source and destination are not the same file + if [ "$(realpath "$src_file")" != "$(realpath "$dest_file")" ]; then + cp "$src_file" "$dest_file" + echo "Copied: $(basename "$src_file")" + else + echo "Skipped (same file): $(basename "$src_file")" + fi +done + + + + +# Remove extension and link to Git +rm "${BONSAI_PATH}/__init__.py" +rm -r "${PACKAGE_PATH}/bonsai" +rm -r "${PACKAGE_PATH}/ifcopenshell" +rm -r "${PACKAGE_PATH}/ifccsv.py" +rm -r "${PACKAGE_PATH}/ifcdiff.py" +rm -r "${PACKAGE_PATH}/bsdd.py" +rm -r "${PACKAGE_PATH}/bcf" +rm -r "${PACKAGE_PATH}/ifc4d" +rm -r "${PACKAGE_PATH}/ifc5d" +rm -r "${PACKAGE_PATH}/ifccityjson" +rm -r "${PACKAGE_PATH}/ifcclash" +rm -r "${PACKAGE_PATH}/ifcpatch" +rm -r "${PACKAGE_PATH}/ifctester" +rm -r "${PACKAGE_PATH}/ifcfm" + +ln -s "${PWD}/src/bonsai/bonsai/__init__.py" "${BONSAI_PATH}/__init__.py" +ln -s "${PWD}/src/bonsai/bonsai" "${PACKAGE_PATH}/bonsai" +ln -s "${PWD}/src/ifcopenshell-python/ifcopenshell" "${PACKAGE_PATH}/ifcopenshell" +ln -s "${PWD}/src/ifccsv/ifccsv.py" "${PACKAGE_PATH}/ifccsv.py" +ln -s "${PWD}/src/ifcdiff/ifcdiff.py" "${PACKAGE_PATH}/ifcdiff.py" +ln -s "${PWD}/src/bsdd/bsdd.py" "${PACKAGE_PATH}/bsdd.py" +ln -s "${PWD}/src/bcf/bcf" "${PACKAGE_PATH}/bcf" +ln -s "${PWD}/src/ifc4d/ifc4d" "${PACKAGE_PATH}/ifc4d" +ln -s "${PWD}/src/ifc5d/ifc5d" "${PACKAGE_PATH}/ifc5d" +ln -s "${PWD}/src/ifccityjson/ifccityjson" "${PACKAGE_PATH}/ifccityjson" +ln -s "${PWD}/src/ifcclash/ifcclash" "${PACKAGE_PATH}/ifcclash" +ln -s "${PWD}/src/ifcpatch/ifcpatch" "${PACKAGE_PATH}/ifcpatch" +ln -s "${PWD}/src/ifctester/ifctester" "${PACKAGE_PATH}/ifctester" +ln -s "${PWD}/src/ifcfm/ifcfm" "${PACKAGE_PATH}/ifcfm" + +# Manually download some third party dependencies +cd "${PACKAGE_PATH}/bonsai/bim/data/gantt" +wget -O jsgantt.js https://raw.githubusercontent.com/jsGanttImproved/jsgantt-improved/master/dist/jsgantt.js +wget -O jsgantt.css https://raw.githubusercontent.com/jsGanttImproved/jsgantt-improved/master/dist/jsgantt.css + +[ -d "$PACKAGE_PATH/bonsai/bim/schema" ] || mkdir -p "$PACKAGE_PATH/bonsai/bim/schema" +cd "${PACKAGE_PATH}/bonsai/bim/schema" +wget -O Brick.ttl https://github.com/BrickSchema/Brick/releases/download/nightly/Brick.ttl diff --git a/src/bonsai/docs/quickstart/ide/linux/launch.json b/src/bonsai/docs/quickstart/ide/linux/launch.json new file mode 100644 index 0000000000..d8f3ad872f --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/linux/launch.json @@ -0,0 +1,18 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + + { + "name": "BonsaiDocsServer", + "type": "debugpy", + "request": "launch", + "program": "/home/falken10vdl/bonsaiDevel/IfcOpenShell/src/bonsai/docs/_build/html", + "args": ["-m", "http.server"], + "preLaunchTask": "Build and Serve Docs", + "console": "integratedTerminal" + } + ] +} diff --git a/src/bonsai/docs/quickstart/ide/linux/tasks.json b/src/bonsai/docs/quickstart/ide/linux/tasks.json new file mode 100644 index 0000000000..dbf3162d3d --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/linux/tasks.json @@ -0,0 +1,22 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Build and Serve Docs", + "type": "shell", + "command": "bash", + "args": [ + "-c", + "cd /home/falken10vdl/bonsaiDevel/IfcOpenShell/src/bonsai/docs/; make html; cd _build/html; python3 -m http.server" + ], + "group": { + "kind": "build", + "isDefault": true + }, + "problemMatcher": [] + } + ] +} + diff --git a/src/bonsai/docs/quickstart/ide/linux_ide.rst b/src/bonsai/docs/quickstart/ide/linux_ide.rst new file mode 100644 index 0000000000..9da0bd068a --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/linux_ide.rst @@ -0,0 +1,727 @@ +Linux +================ + + +This quickstart will help you set up your Linux machine to explore the sourcecode of Bonsai +or develop and debug your blender scripts in VSCode. This has the benefit of having a complete +development environment where you can explore the code, make changes, debug (break-points, watch +variable and stack contents, etc. ) and see the results in blender + +- Steps 1-6 will get you started with VSCode to develop and debug python scripts in Blender. + +- Steps 7-14 will allow you to interact with GitHub to make changes to the Bonsai project. + +- Step 15 will allow you to download someone else's pull request and test it in your local machine. + +We will be using AlmaLinux 9 as our operating system and Visual Studio Code as our +Integrated Development Environment (IDE) and we will create a dedicated user for Development. + +1. **Create Development User**: Open up a terminal (typically hitting "Windows" key + and writing "terminal" in the search field) + + .. image:: images/launch-terminal.png + :width: 200 px + + .. code-block:: bash + + sudo useradd falken10vdl + sudo passwd falken10vdl + sudo usermod -aG wheel falken10vdl + + .. image:: images/create-user.png + :width: 500 px + + .. tip:: + + If for some reason you need to delete the user, you can use the following command: + + .. code-block:: bash + + sudo userdel -r falken10vdl + +2. **Install Blender for the created user**: We will install blender locally in the users home directory. + We must check that we are following the `Systems requirements `__. + + We will download Blender 4.2 from the `Blender download page `__. + In particular, we take the `4.2 LTS `__ for Linux. + + We will download the Linux 64 bit version: + + https://www.blender.org/download/release/Blender4.2/blender-4.2.8-linux-x64.tar.xz + + .. code-block:: bash + + wget https://download.blender.org/release/Blender4.2/blender-4.2.8-linux-x64.tar.xz + tar -xvf blender-4.2.8-linux-x64.tar.xz + mv blender-4.2.8-linux-x64 /home/falken10vdl/.local/share/applications/blender-4.2.8-linux-x64 + + .. warning:: + + If the directory */home/falken10vdl/.local/bin/* does not exist, we will create it. + + .. code-block:: bash + + mkdir -p /home/falken10vdl/.local/bin/ + + We will create a symbolic link to the blender executable in the bin directory and we will also modify the blender.desktop file to open in a terminal and to have a custom icon. + + .. code-block:: bash + + ln -s /home/falken10vdl/.local/share/applications/blender-4.2.8-linux-x64/blender /home/falken10vdl/.local/bin/blender + sed -i 's/^Terminal=.*/Terminal=true/' /home/falken10vdl/.local/share/applications/blender-4.2.8-linux-x64/blender.desktop + sed -i 's|^Icon=.*|Icon=/home/falken10vdl/.local/share/applications/blender-4.2.8-linux-x64/blender.svg|' /home/falken10vdl/.local/share/applications/blender-4.2.8-linux-x64/blender.desktop + + .. image:: images/blender-installation-1.png + :width: 1000 px + + .. image:: images/blender-installation-2.png + :width: 1000 px + + CONGRATULATIONS! You have now Blender installed in your machine. You can launch it by typing `blender` in the terminal. + + Now install the Bonsai Blender extension. Follow the `Unstable installation `__. + +3. **Install VSCode**: Log in as the new created user (*falken10vdl* in this example) + and install `Visual Studio Code `__. + + .. code-block:: bash + + sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc + echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\nautorefresh=1\ntype=rpm-md\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" | sudo tee /etc/yum.repos.d/vscode.repo > /dev/null + dnf check-update + sudo dnf install code # or code-insiders + + .. image:: images/install-vscode.png + :width: 1000 px + +4. **Adjust Python version in VSCode as in Blender**: Although not extrictly mandatory, this is + a good practice step to ensure that the Python version in VSCode matches the one in Blender. + + Check the Python version in Blender by going to :menuselection:`Scripting`. In the Python Console you can see the version number of the Python + interpreter + + .. image:: images/blender-python-version.png + :width: 1000 px + + + In our case it is version 3.11.7 + + We will need to install the closest version in our Linux machine. + + We check in `Python Downloads `__. + + .. image:: images/python-downloads.png + :width: 1000 px + + The closest version is 3.11.11. So we download the Gzipped source tarball and install it. + + We use the "altinstall" option to avoid overwriting the default Python version which could cause + conflicts with the default installed version of the linux operating system. + + .. code-block:: bash + + wget https://www.python.org/ftp/python/3.11.11/Python-3.11.11.tgz + tar -xvf Python-3.11.11.tgz + cd Python-3.11.11 + sudo dnf install gcc openssl-devel bzip2-devel libffi-devel + ./configure --enable-optimizations + nproc + make -j 4 #adjust the value to the one provided by nproc + sudo make altinstall + + + .. image:: images/install-python-1.png + :width: 1000 px + + .. image:: images/install-python-2.png + :width: 1000 px + + .. image:: images/install-python-3.png + :width: 1000 px + + .. image:: images/install-python-4.png + :width: 1000 px + + .. image:: images/install-python-5.png + :width: 1000 px + + After this, we have the 3.11 python version installed in our machine. It is reachable by typing + `python3.11` in the terminal. + + .. code-block:: bash + + python3.11 -V + + .. image:: images/install-python-6.png + :width: 1000 px + + CONGRATULATIONS! You have now a Python version in VSCode similar to the one run by Blender. + +5. **Connect VSCode to Blender by means of VSCode's extension: "Blender Development"**: This steps + is crucial to be able to develop and debug scripts in VSCode ans interactively see the results in Blender. + + Launch VSCode and go to the Extensions tab, search for Blender Development and install it. + + .. image:: images/VSCode-blender-extension.png + :width: 1000 px + + This will also install some Python related extensions. + + Finally create a sample python file and check the Python interpreter version in the bottom left corner. + + :menuselection:`File --> New File... --> Python File` + + + .. image:: images/VSCode-python-version-linux.png + :width: 1000 px + + +6. **Test that you can develop python scripts in VSCode for Blender**: Create a sample blender python file. + you can use whatever blender python script you want. We will use this one from the blender documentation: + `Example Panel `__ + + .. code-block:: python + + import bpy + + class HelloWorldPanel(bpy.types.Panel): + """Creates a Panel in the Object properties window""" + bl_label = "Hello World Panel" + bl_idname = "OBJECT_PT_hello" + bl_space_type = 'PROPERTIES' + bl_region_type = 'WINDOW' + bl_context = "object" + + def draw(self, context): + layout = self.layout + + obj = context.object + + row = layout.row() + row.label(text="Hello world!", icon='WORLD_DATA') + + row = layout.row() + row.label(text="Active object is: " + obj.name) + row = layout.row() + row.prop(obj, "name") + + row = layout.row() + row.operator("mesh.primitive_cube_add") + + + def register(): + bpy.utils.register_class(HelloWorldPanel) + + + def unregister(): + bpy.utils.unregister_class(HelloWorldPanel) + + + if __name__ == "__main__": + print("Hello World: run from Blender Text Editor") + else: + print("Hello World: run from VSCode") + print(f"NOTE. __name__ is : {__name__}") + + register() + + .. tip:: + + Although blender has builtin the python modules for bpy, it is a good practice to install the "fake-bpy-module" in your local python environment. + This will allow VSCode to provide autocompletion and other features. You can install it by running the following command in the VSCode terminal: + + .. code-block:: + + python3.11 -m pip install fake-bpy-module-latest + + + .. image:: images/install-bpy-fake-linux.png + :width: 1000 px + + + + We have changed the last part of the script since running from VSCode has some subtle differences compared to running from the Blender Text Editor. In particular the special variable `__name__` is different. + + - Press CTRL-SHIFT-P and type "Blender: Start". Blender will start. + - Press CTRL-SHIFT-P and type "Blender: Run Script". The script will run and the output will be seen in Blender! + + As you can see below. We have set a break-point in line 37 (see point 13 below for another example of setting a break-point). We can inspect in the left side the local variables, global variables, add watches, + check the stack, etc. For example we can see that __name__ has a valuee of "" Instead of "__main__". + + .. image:: images/script-blender-vscode.png + :width: 1000 px + + + Once we continue execution we can check in the VSCode Terminal the output and in Blender the panel created by the script. + + .. image:: images/script-blender-vscode-2.png + :width: 1000 px + + CONGRATULATIONS! You have now a development environment ready to speedup your python scripting in Blender. + + +X. **BONUS: Editing Bonsai Documentation**: Please refer to `Writing documentation `__ for details on how to edit and contribute + documentation. Here we just summarize the steps to integrate that workflow in VSCode and using Inkscape. + + - Download and install Inkscape from `Inkscape download page `__. In our case we will use `Inkscape 1.4 Linux AppImage `__. + + .. note:: + + You might already have Inkscape in your Linux distribution or can install it from the distribution package manager. In that case you can skip this step. + + - The file below has the style annotation for the Bonsai documentation. + + .. container:: blockbutton + + `Download style annotation file `__ + + It contains some shapes and styles that you can use to create your own diagrams. + + .. image:: images/inkscape-annotation-template.png + :width: 1000 px + + - Open some screenshot file you want to add annotations in Inkscape and also open this template. You can then copy paste from the temaplate to the screenshot file. + + .. warning:: + When copying the shapes for your convenience just make sure that you do not have selected the option "When scaling objects, scale the stroke width by the same proportion" to keep the style width right. + + .. image:: images/inkscape-scaling-outline.png + :width: 1000 px + + - Once done you can export your edited screenshot as PNG to be used in the docummentation. :menuselection:`File --> Export...` and click in the Export button on bottom right corner. + - As described in `Writing documentation `__ you need to have sphinx installed in your system. + You can simply run the following command in the terminal: + + .. code-block:: bash + + yum install python-sphinx + + and then install the theme and theme dependencies: + + .. code-block:: bash + + python3.11 -m pip install furo + python3.11 -m pip install sphinx-autoapi + python3.11 -m pip install sphinx-copybutton + + - To speedup your workflow you can add the following VSCode files in the .vscode folder of your cloned repository. In our case it is */home/falken10vdl/bonsaiDevel/IfcOpenShell/.vscode* + - Make sure to edit them with the right paths in your system. + + - `launch.json `__ + + .. image:: images/launch-linux-jason.png + :width: 1000 px + + - `tasks.json `__ + + .. image:: images/tasks-linux-jason.png + :width: 1000 px + + - Now you can use the debug tool in VSCode to regenerate the html documentation by cliking the "Play" button *BonsaiDocsServer (IfcOpenShell)* in the top left corner of the debug tool. + + .. image:: images/bonsai-doc-server.png + :width: 1000 px + + - Once the server is started you can open a browser and go to the following URL: + http://localhost:8000/ and you will see the documentation. + + - In order to rebuild the documentation you need to stop the server and run the command again. You can do this by clicking in the "Abort" button in the bottom right corner of the debug tool. + + .. image:: images/doc-server-running.png + :width: 1000 px + + CONGRATULATIONS! And happy documenting! + + + +Now let's find out how to interact with GitHub in order to make changes to the Bonsai project. + + +7. **Install GitHub related VSCode extensions**: To facilitate the use of git commands and pulling + and pushing files from a local repository towards github, please install as well the following VSCode + extensions: + + - GitHub Pull Requests + - GitHub Repositories + - Remote Repositories + + Optionaly you can also install Copilot extensions + + - GitHub Copilot + - GitHub Copilot Chat + + .. image:: images/VSCode-extensions.png + :width: 500 px + + +8. **Fork IfcOpenShell project from GitHub**: For this step you will need an account on GitHub. + Once you have a registered account you can find it under https://github.com/YOURGITHUBUSERID + In the example for *falken10vdl* the link is https://github.com/falken10vdl + + .. image:: images/GitHubUser.png + :width: 1000 px + + Go to the `IfcOpenShell GitHub page `__. And + click on the Fork button. Please make sure that you are logged with your GitHub account as shown in the + top right corner of the page. + + .. image:: images/fork-bonsai.png + :width: 1000 px + + Once the fork is generated you will be redirected to your own fork of the IfcOpenShell project. + + .. image:: images/forked-bonsai.png + :width: 1000 px + + Now we will clone the forked repository to our local machine. + +9. **Clone bonsai to our development environment**: Launch VSCode + Select the Source Control tool. Then :menuselection:`Clone repository` and then select "Clone from GitHub". + + .. image:: images/cloning-from-github.png + :width: 1000 px + + A series of steps will be required to authenticate with GitHub. You will need to provide your GitHub credentials. + Once VSCode has authenticated yourself in GitHub, you will be able to select the repository you want to clone. + In this case we will clone the IfcOpenShell repository. + + .. image:: images/selecting-forked-repo.png + :width: 1000 px + + VSCode will ask you to select a folder where the repository will be cloned. and it will start the cloning process. + + Once finished, you will see the repository in the Explorer tool. + + .. image:: images/cloned-repo.png + :width: 1000 px + +10. **Link the Bonsai addon to the local cloned repository**: We will now edit the following + script that establishes links from the unstable-installation to the cloned repository so we + can easily see the changes done in the cloned repository taken effect when we load blender + locally. + + .. container:: blockbutton + + `Download dev_environment.sh `__ + + Edit the file to match the paths in your system. In our case we will edit the following lines: + + - REPO_PATH="$HOME/bonsaiDevel/IfcOpenShell" + - BLENDER_PATH="$HOME/.config/blender/4.2" + - PACKAGE_PATH="${BLENDER_PATH}/extensions/.local/lib/python3.11/site-packages" + - BONSAI_PATH="${BLENDER_PATH}/extensions/raw_githubusercontent_com/bonsai" + + We execute the script in the terminal. Confirm the data and the script will create the necessary links. + + .. code-block:: bash + + ./dev_environment.sh + + .. image:: images/dev-environment-sh.png + :width: 1000 px + + .. image:: images/dev-environment-sh-executed.png + :width: 1000 px + + .. warning:: + + If you receive an error like this: + + .. code-block:: bash + + cp: cannot stat '/home/falken10vdl/.config/blender/4.2/extensions/.local/lib/python3.11/site-packages/ifcopenshell/*_wrapper*': No such file or directory + + It means that you have not installed the Bonsai Blender extension. Please refer to tha + last part of point 2. above and follow the `Unstable installation `__. + + +11. **Adjust the VSCode Blender extension**: We will now make some adjustments to the VSCode Blender extension to ease the reload of the addon. + Select the Extensions tool. Then :menuselection:`Blender Development` and then select :menuselection:`Settings`. + + .. image:: images/VSCode-blender-extension-settings.png + :width: 1000 px + + Click twice in "Add Item" within the *Blender: Additonal Arguments* section and add the following two items (adapt *Testing.ifc* to the name of the IFC file you want to test during Bonsai development): + + - --python-expr + - import bpy; import os; os.chdir('/home/falken10vdl'); bpy.ops.bim.load_project(filepath='/home/falken10vdl/Documents/sampleIFC/Testing.ifc', should_start_fresh_session=True, use_detailed_tooltip=True) + + .. image:: images/VSCode-blender-additional-arguments-linux.png + :width: 1000 px + + Make sure that Blender > Addon: Just My code is not selected (This allows to set the breakpoints anywhere in the source code). + + .. image:: images/just-my-code-false.png + :width: 1000 px + + + .. warning:: + + This way to use the VSCode Blender extension is not the standard one. Refer to the `VSCode Blender extension documentation `__ for the standard way to use it. + The reason behind is that this allows us to start VSCode in the top of the cloned repository so + all the Git related funtionality in VSCode works properly and we have a complete view from VSCode + :menuselection:`Explorer` tool of the whole repository. + + Bonsai is a big project with a lot of dependencies + so reloading it is not an easy task (see discussion in https://community.osarch.org/discussion/1650/vscode-and-jacquesluckes-blender-vscode/p1). We have taken the pragmatic approach to start blender with a specific file (*Testing.ifc*) + and then we can reload the addon from the Blender UI which also upload automatically the changes in the addon and the testing file + To summarize: + + - We need *Blender > Addon: Just My code* to get the breakpoint functionality even if the addon is not "registered/loaded" to the extension (due to the root folder we use) + - We need *Blender: Additonal Arguments* to automatically load the Testing.ifc file when we start Blender from VSCode (We do not use *Blender:Reload Addons* since it does not work in our case) + + Instead of restarting Blender from VSCode, we use the Blender UI that, as explainedin the next step, it provides a simple way to get the addon and the Testing file reloaded. + +12. **Launch blender from VSCode**: We are now ready to launch Blender from VSCode. + Open VSCode. Open the cloned repository if not already open. + Press CTRL-SHIFT-P and type "Blender: Start". + + .. image:: images/VSCode-blender-start.png + :width: 1000 px + + Blender will start loading the Testing.ifc file. You can now start exploring the code and make changes to the addon! + + .. image:: images/VSCode-and-blender.png + :width: 1000 px + + In order to be able to restart blender (and reload the addons + reload the Testing file) we need to + enable "Developer Extras" and also a good practice is to enable "Python Tooltips" in :menuselection:`Edit --> Preferences --> Interface`. + + .. image:: images/enable-developer-extras.png + :width: 500 px + + Once these are enabled, you can press F3 and write "restart" to restart Blender. + + .. image:: images/restart-blender.png + :width: 1000 px + + + .. note:: + + Once you enable "Developer Extras" you will see that you can right click in the UI and select "Source Code" to see the code behind the UI. For example in the image below you can + right click in the "Generate SVG" and select "Edit Source". + + .. image:: images/edit_source.png + :width: 1000 px + + Then in the "Scripting" tab you can click and select a new editor windows that has been created (in this case it is called "uy.py"). + + .. image:: images/scripting_ui_code.png + :width: 500 px + + If you select it, you will see the relevant code with a vertical blue line marking the exact point in the source code where the UI element is defined. + + .. image:: images/marked_code.png + :width: 1000 px + + From there it is quite usefull to search in VSCode to find the relevant file within the Bonsai source code. For that you can go to :menuselection:`Edit --> Find in Files`. + + .. image:: images/vscode_search_in_files.png + :width: 350 px + + Then you can click in the results to get the file opened in the editor. + + .. image:: images/vscode_search_results.png + :width: 1000 px + + + .. tip:: + + Once you enable "developer Extras" you will be able to select in :menuselection:`Edit --> Preferences --> Experimental --> Debugging` a number of options related to code development. + + .. image:: images/blender_experimental_debugging.png + :width: 500 px + + In the case case of Bonsai. You have the TAB :menuselection:`Quality & Coordination --> Debug --> Experimental --> Debugging` that also provides a number of tools to ease the development process. + + .. image:: images/bonsai_debug.png + :width: 500 px + + Finally, there are a number of usefull Blender addons that can also help you in the development process. For example "Icon Viewer" or "Math vis". + + .. image:: images/blender_development_addons.png + :width: 500 px + +13. **Add a break-point**: Let's add a break-point in the code to see how it works. + Press CTRL_SHIFT_P and type "Blender: Start". Blender will start. + Open the cloned folder and go to *src > bonsai > bonsai > bim > module > light > prop.py* and go to line 75. + Add a line for a print statement and click on the left side of the line number to add a break-point. + + .. code-block:: python + + 74 def update_shadow_mode(self, context): + 75 print("Shadow mode", self.shadow_mode) + 76 if self.shadow_mode == "SHADING": + + + Set a break-point in line 75. + + .. image:: images/break-point.png + :width: 1000 px + + In Blender. Go To SOLAR ANALYSYS Tool in Bonsai and Click in "No Shadow", "Shaded" or "Rendered" + + .. image:: images/trigger-breakpoint.png + :width: 1000 px + + + This will trigger the break-point. See how the execution is stopped at the break-point. + + .. image:: images/break-point-stop.png + :width: 1000 px + + Click in the debugging tools the option for "step over" (F10). + + .. image:: images/step-over-linux.png + :width: 150 px + + You can see the print statement executed and the output in the VSCode internal terminal. + + .. image:: images/print-to-console.png + :width: 1000 px + + From here you can watch the local variables, global variables, add watches, check the stack, etc. + Resume execution or move step by step to see how the code is executed. + + CONGRATULATIONS! You have now a development environment ready to explore the Bonsai code and contribute to the project. + +14. **Make changes and do a Pull Request to the project**: In the previous steps we got a complete IDE to explore and make changes to the Bonsai sourcecode. + In this step we will provide a simple workflow of using Git commands within VSCode to make changes and do a Pull Request to the project. + Bonsai changes very fast so our cloned repository will be outdated very soon. We propose to do the following: + + a. Check in our GitHub page if our project fork (https://github.com/falken10vdl/IfcOpenShell) is outdated compared to the IfcOpenShell main branch (https://github.com/IfcOpenShell/IfcOpenShell). + b. Sync our fork with the upstream branch (if needed). + c. Pull the changes in our porject fork to our local repository (/home/falken10vdl/bonsaiDevel). + d. Create a new branch in our local repository (example: *DOC_QS_IDE*) + e. Publish the branch to our project fork in GitHub. + f. Make changes in the code. + g. Commit the changes. + h. Push the changes to our project fork. + i. Create a Pull Request to the upstream main branch of the IfcOpenShell project. + + Letis see below the steps with an example of changing the documentation of the Quickstart guide for the IDE in Linux. + + a. Check in our GitHub page if our project fork is outdated. Click *Update branch* + + .. image:: images/check-fork.png + :width: 1000 px + + b. After clicking *Update branch* our fork is up to date with the upstream main branch. + + .. image:: images/sync-fork.png + :width: 1000 px + + c. Pull the changes in our porject fork to our local repository + + .. image:: images/pull-changes.png + :width: 1000 px + + d. Create a new branch in our local repository by clicking in the current branch name in the bottom left corner of the VSCode window. Give a name to the branch and press Enter. + + .. image:: images/create-branch.png + :width: 1000 px + + The new branch is created and we can see it in the bottom left corner of the VSCode window. + + .. image:: images/new-branch-local.png + :width: 1000 px + + e. Publish the branch to our project fork in GitHub by clicking in the publish button (*little cloud with up arrow*) in the bottom + left corner of the VSCode window. Select as origin the project fork. + + .. image:: images/new-branch-publish-to-private-github.png + :width: 1000 px + + Check that the branch is now in our project fork in GitHub. + + .. image:: images/new-branch-in-private-github.png + :width: 1000 px + + f. Make changes in the code. In this case we will change documentation by adding a Quickstart for the IDE in Linux. :) + + .. image:: images/make-changes-linux.png + :width: 1000 px + + .. note:: + + Bonsai uses "Black" as the code formatter. You can install it by running the following command in the terminal: + + .. code-block:: bash + + python3.11 -m pip install black + + Please make sure that before you commit the changes you run the following command in the terminal in the IfcOpenShell root folder: + + .. code-block:: bash + + black . + + g. Commit the changes. + First provide your user name and email to Git. + + .. image:: images/git-user-email-linux.png + :width: 1000 px + + Then commit the changes by clicking in the check mark in the Source Control tool. + + .. image:: images/commit-changes-linux.png + :width: 1000 px + + Accept the staging of the changes prior to commit. + + .. image:: images/staging-prior-commit.png + :width: 350 px + + h. Push the changes to our new branch in the github project fork. + + .. image:: images/push-to-private-fork-new-branch.png + :width: 1000 px + + Check that the changes are in the project fork in GitHub. You can see that the directory *ide* has been added, for example. + + .. image:: images/private-fork-new-branch-updated-linux.png + :width: 1000 px + + + i. Create a Pull Request to the upstream main branch of the IfcOpenShell project. + Go to your GitHub page and you will see that the new branch has 1 commit ahead of the upstream main branch. Click in the *Compare & pull request* button. + + .. image:: images/compare-and-pull-request.png + :width: 1000 px + + Verify that the changes are correct, add a description and click in the *Create pull request* button. + + .. image:: images/pull-request-linux.png + :width: 1000 px + + .. note:: + + If you need to update the Pull Request with new changes, you can do it by making the changes in the local repository and then commit and push them to the same branch. + The Pull Request will be updated automatically. You can also add comments to the Pull Request to explain the changes made. + + .. warning:: + + Sometimes the process of changing the initial code for the Pull Request takes enough time that already the upstream main branch has changed significately. This means that a direct merge to the upstream branch + is not possible without conflicts. In this case you will need to rebase the Pull Request branch with the upstream main branch.This takes all your commits from the current PR branch and reapplies them one by one on top of the latest commits + in the target branch (which should be the upstream main branch). This is a bit more complex process and you can refer to the `Using Git source control in VS Code `__ for more information. + + .. image:: images/rebase_branch.png + :width: 1000 px + + + CONGRATULATIONS! You have now made a change in the Bonsai project and created a Pull Request to the main branch of the project. Happy coding and documenting! + +15. **Test someone else's Pull Request**: Ofen times you want to provide feedback to someone else's Pull Request. + A simple way to do this is by using the GitHub Pull Request extension in VSCode. Please refer to `GitHub Pull Requests in Visual Studio Code `__ for more information. + + .. image:: images/checkout_pull_request_vscode.png + :width: 1000 px + + This will fetch the branch of the Pull Request and you will be able to test it as if you had created your own branch. + + .. image:: images/pull_request_see.png + :width: 1000 px + + You can also use the GitHub Pull Request extension to review the Pull Request and provide comments. And of course the rest of the VSCode functionality to test, debug, improve, etc. the code. + + CONGRATULATIONS! and happy testing! diff --git a/src/bonsai/docs/quickstart/ide/macos_ide.rst b/src/bonsai/docs/quickstart/ide/macos_ide.rst new file mode 100644 index 0000000000..446bf898a1 --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/macos_ide.rst @@ -0,0 +1,8 @@ +MacOS +================ + +This quickstart will help you set up your MacOS machine to explore the sourcecode of Bonsai. + +You will be able to update or contribute to the official documentation and also explore the code behind Bonsai's functionalities to troubleshoot or propose new features for Bonsai. + +Please be patient while this documentation is created. Meanwhile you can check the :doc:`/quickstart/ide/linux_ide` guide which should be fairly similar. \ No newline at end of file diff --git a/src/bonsai/docs/quickstart/ide/windows/dev_environment.bat b/src/bonsai/docs/quickstart/ide/windows/dev_environment.bat new file mode 100644 index 0000000000..a5007aa19d --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/windows/dev_environment.bat @@ -0,0 +1,100 @@ +@echo off + +setlocal enabledelayedexpansion + + +rem ADAPT setting REPO_PATH to use custom path for IfcOpenShell repository. +rem Otherwise by default it is assumed script is executed from IfcOpenShell directory. +SET REPO_PATH=%HOMEDRIVE%\Users\%USERNAME%\Documents\bonsaiDevel\IfcOpenShell +SET BLENDER_PATH=%HOMEDRIVE%\Users\%USERNAME%\AppData\Roaming\Blender Foundation\Blender\4.2 +SET PACKAGE_PATH=%BLENDER_PATH%\extensions\.local\lib\python3.11\site-packages +SET BONSAI_PATH=%BLENDER_PATH%\extensions\raw_githubusercontent_com\bonsai + +echo SETUP BONSAI ADD-ON LIVE DEVELOPMENT ENVIRONMENT +echo Update REPO_PATH, BLENDER_PATH, PACKAGE_PATH, BONSAI_PATH in the script above. +echo This script needs to be run as administrator (to create symbolic links) +echo Make sure you have followed these steps before proceeding :) +echo. +echo Currently set paths: +if not defined REPO_PATH ( + echo REPO_PATH is not set, assuming we're already in IfcOpenShell directory. + set REPO_PATH=%cd% +) +rem Print summary of paths +echo. +echo Please review if the following is right: +echo PWD: %CD% +echo REPO PATH (.....\IfcOpenshell): %REPO_PATH% +echo BLENDER PATH: %BLENDER_PATH% +echo PACKAGE PATH (.....\extensions\.local\lib\python3.11\site-packages): %PACKAGE_PATH% +echo BONSAI PATH (.....\extensions\raw_githubusercontent_com\bonsai): %BONSAI_PATH% +echo. +rem Prompt user to continue +pause + + +echo Changing to the Git repository directory... +cd %REPO_PATH% + +rem Add files that need to be ignored in push to GiHub (.gitignore) +set "FILE=.gitignore" +set "STRING=*.so" + +rem Check if the file exists and contains the string +if not exist "%FILE%" ( + echo %STRING% >> "%FILE%" + echo "%FILE%" does not exist + echo Added '%STRING%' to %FILE% +) else ( + findstr /L "%STRING%" "%FILE%" >nul + if errorlevel 1 ( + echo %STRING% >> "%FILE%" + echo %STRING% not found in %FILE% + echo Added %STRING% to %FILE% + ) else ( + echo '%STRING%' already exists in %FILE% + ) +) + +echo Copy over compiled IfcOpenShell files... +copy "%PACKAGE_PATH%\ifcopenshell\*_wrapper*" "%CD%\src\ifcopenshell-python\ifcopenshell\" + +echo Remove extension and link to Git... +del "%BONSAI_PATH%\__init__.py" +rd /S /Q "%PACKAGE_PATH%\bonsai" +rd /S /Q "%PACKAGE_PATH%\ifcopenshell" +del "%PACKAGE_PATH%\ifccsv.py" +del "%PACKAGE_PATH%\ifcdiff.py" +del "%PACKAGE_PATH%\bsdd.py" +rd /S /Q "%PACKAGE_PATH%\bcf" +rd /S /Q "%PACKAGE_PATH%\ifc4d" +rd /S /Q "%PACKAGE_PATH%\ifc5d" +rd /S /Q "%PACKAGE_PATH%\ifccityjson" +rd /S /Q "%PACKAGE_PATH%\ifcclash" +rd /S /Q "%PACKAGE_PATH%\ifcpatch" +rd /S /Q "%PACKAGE_PATH%\ifctester" +rd /S /Q "%PACKAGE_PATH%\ifcfm" + +mklink "%BONSAI_PATH%\__init__.py" "%CD%\src\bonsai\bonsai\__init__.py" +mklink /D "%PACKAGE_PATH%\bonsai" "%CD%\src\bonsai\bonsai" +mklink /D "%PACKAGE_PATH%\ifcopenshell" "%CD%\src\ifcopenshell-python\ifcopenshell" +mklink "%PACKAGE_PATH%\ifccsv.py" "%CD%\src\ifccsv\ifccsv.py" +mklink "%PACKAGE_PATH%\ifcdiff.py" "%CD%\src\ifcdiff\ifcdiff.py" +mklink "%PACKAGE_PATH%\bsdd.py" "%CD%\src\bsdd\bsdd.py" +mklink /D "%PACKAGE_PATH%\bcf" "%CD%\src\bcf\bcf" +mklink /D "%PACKAGE_PATH%\ifc4d" "%CD%\src\ifc4d\ifc4d" +mklink /D "%PACKAGE_PATH%\ifc5d" "%CD%\src\ifc5d\ifc5d" +mklink /D "%PACKAGE_PATH%\ifccityjson" "%CD%\src\ifccityjson\ifccityjson" +mklink /D "%PACKAGE_PATH%\ifcclash" "%CD%\src\ifcclash\ifcclash" +mklink /D "%PACKAGE_PATH%\ifcpatch" "%CD%\src\ifcpatch\ifcpatch" +mklink /D "%PACKAGE_PATH%\ifctester" "%CD%\src\ifctester\ifctester" +mklink /D "%PACKAGE_PATH%\ifcfm" "%CD%\src\ifcfm\ifcfm" + +echo Manually downloading some third party dependencies... +curl https://raw.githubusercontent.com/jsGanttImproved/jsgantt-improved/master/dist/jsgantt.js -o "%PACKAGE_PATH%\bonsai\bim\data\gantt\jsgantt.js" +curl https://raw.githubusercontent.com/jsGanttImproved/jsgantt-improved/master/dist/jsgantt.css -o "%PACKAGE_PATH%\bonsai\bim\data\gantt\jsgantt.css" +IF NOT EXIST "%PACKAGE_PATH%\bonsai\bim\schema" mkdir "%PACKAGE_PATH%\bonsai\bim\schema" +curl -L https://github.com/BrickSchema/Brick/releases/download/nightly/Brick.ttl -o "%PACKAGE_PATH%\bonsai\bim\schema\Brick.ttl" + + +pause \ No newline at end of file diff --git a/src/bonsai/docs/quickstart/ide/windows/launch.json b/src/bonsai/docs/quickstart/ide/windows/launch.json new file mode 100644 index 0000000000..941c9b3f6b --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/windows/launch.json @@ -0,0 +1,18 @@ +{ + // Use IntelliSense to learn about possible attributes. + // Hover to view descriptions of existing attributes. + // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 + "version": "0.2.0", + "configurations": [ + + { + "name": "BonsaiDocsServer", + "type": "debugpy", + "request": "launch", + "program": "C:/Users/falke/Documents/bonsaiDevel/IfcOpenShell/src/bonsai/docs/_build/html", + "args": ["-m", "http.server"], + "preLaunchTask": "Build and Serve Docs", + "console": "integratedTerminal" + } + ] +} \ No newline at end of file diff --git a/src/bonsai/docs/quickstart/ide/windows/tasks.json b/src/bonsai/docs/quickstart/ide/windows/tasks.json new file mode 100644 index 0000000000..6d8a1ff195 --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/windows/tasks.json @@ -0,0 +1,24 @@ +{ + // See https://go.microsoft.com/fwlink/?LinkId=733558 + // for the documentation about the tasks.json format + "version": "2.0.0", + "tasks": [ + { + "label": "Build and Serve Docs", + "type": "shell", + "command": "powershell", + "args": [ + "-NoProfile", + "-ExecutionPolicy", + "Bypass", + "-Command", + "cd C:/Users/falke/Documents/bonsaiDevel/IfcOpenShell/src/bonsai/docs/; .\\make html; cd _build/html; python -m http.server" + ], + "group": { + "kind": "build", + "isDefault": true + }, + "problemMatcher": [] + } + ] +} \ No newline at end of file diff --git a/src/bonsai/docs/quickstart/ide/windows_ide.rst b/src/bonsai/docs/quickstart/ide/windows_ide.rst new file mode 100644 index 0000000000..a2cf1e0d6c --- /dev/null +++ b/src/bonsai/docs/quickstart/ide/windows_ide.rst @@ -0,0 +1,684 @@ +Windows +================ + +This quickstart will help you set up your MS Windows machine to explore the sourcecode of Bonsai +or develop and debug your blender scripts in VSCode. This has the benefit of having a complete +development environment where you can explore the code, make changes, debug (break-points, watch +variable and stack contents, etc. ) and see the results in blender + +- Steps 1-6 will get you started with VSCode to develop and debug python scripts in Blender and explore the Bonsai sourcecode and documentation. + +- Steps 7-14 will allow you to interact with GitHub to make changes to the Bonsai project. + +- Step 15 will allow you to download someone else's pull request and test it in your local machine. + +We will be using Windows 11 as our operating system and Visual Studio Code as our +Integrated Development Environment (IDE) and we will create a dedicated user for Development. + +.. note:: + In the following steps we will be installing a number of applications. There are several ways to install them and that has impact on whether Windows is able to find the relevant binaries. In general if you have issues in the steps below + related to not being able to find binaries, please check that the installation path is in the PATH environment variable. You can hit "Windows" key and write "environment variables". + + .. image:: images/environment-variables.png + :width: 500 px + + And then go to :menuselection:`System Properties --> Advanced -->Environment Variables`. + + Check that the installation path is in the PATH variable. If not, you can add it by clicking in the :menuselection:`Edit... --> New`. + + .. image:: images/windows-path.png + :width: 500 px + + +1. **Create Development User**: Open Windows Settings (typically hitting "Windows" key + and writing "settings" in the search field) and then go to :menuselection:`Accounts --> Other users`. + Click on :menuselection:`Add account` and then add a new user. We will name it *falken10vdl*. + + + .. image:: images/win-add-user.png + :width: 500 px + + +2. **Install Blender for the created user**: We will install blender locally in the users home directory. + We must check that we are following the `Systems requirements `__. + + We will download Blender 4.2 from the `Blender download page `__. + In particular, we take the `4.2 LTS `__ for Windows. + + We will download the Windows - Portable (.zip) version: + + https://www.blender.org/download/release/Blender4.2/blender-4.2.8-windows-x64.zip + + Unzip the file in the user home directory. In our case it is *C:\\Users\\falke\\Documents\\blender-4.2.8-windows-x64* (the user *falken10vdl* has as home directory *C:\\Users\\falke*). + + CONGRATULATIONS! You have now Blender installed locally in your machine. You can launch it by double clicking in blender.exe which is situated in the previous folder. + + Now install the Bonsai Blender extension. Follow the `Unstable installation `__. + + CONGRATULATIONS! You have now the Bonsai Blender extension installed in your local Blender installation. + + +3. **Install VSCode**: Log in as the new created user (*falken10vdl* in this example) + and install `Visual Studio Code `__. + + + +4. **Adjust Python version in VSCode as in Blender**: This is a good practice step to + ensure that the Python version in VSCode matches the one in Blender. + + Check the Python version in Blender by going to :menuselection:`Scripting`. In the Python Console you can see the version number of the Python + interpreter + + .. image:: images/blender-python-version.png + :width: 1000 px + + + In our case it is version 3.11.7 + + We will need to install the closest version in our Linux machine. + + We check in either in Microsoft store or `Python Downloads `__. + + The closest version is 3.11 in Microsoft Store. So we installing by clicking in :menuselection:`Get`. + + After this, we have the 3.11 python version installed in our machine. It is reachable by typing + `python3.11` in the terminal. + + .. code-block:: bash + + python3.11 -V + + .. image:: images/python-version.png + :width: 500 px + + Finally create a sample python file and check the Python interpreter version in the bottom left corner. Select the + Python interpreter that matches the one in Blender. In our case it is 3.11. + + :menuselection:`File --> New File... --> Python File` + + + .. image:: images/VSCode-python-version-windows.png + :width: 1000 px + + CONGRATULATIONS! You have now a Python version in VSCode similar to the one run by Blender. + +5. **Connect VSCode to Blender by means of VSCode's extension: "Blender Development"**: This steps + is crucial to be able to develop and debug scripts in VSCode and interactively see the results in Blender. + + Launch VSCode and go to the Extensions tab, search for Blender Development and install it. + + .. image:: images/VSCode-blender-extension.png + :width: 1000 px + + This will also install some Python related extensions. + +6. **Test that you can develop python scripts in VSCode for Belnder**: Create a sample blender python file under adirectory + for example *C:\\Users\\falke\\Documents\\bonsaiDevel\\scripts*. You can use whatever blender python script you want. + We will use this one from the blender documentation: + + `Example Panel `__ + + .. code-block:: python + + import bpy + + class HelloWorldPanel(bpy.types.Panel): + """Creates a Panel in the Object properties window""" + bl_label = "Hello World Panel" + bl_idname = "OBJECT_PT_hello" + bl_space_type = 'PROPERTIES' + bl_region_type = 'WINDOW' + bl_context = "object" + + def draw(self, context): + layout = self.layout + + obj = context.object + + row = layout.row() + row.label(text="Hello world!", icon='WORLD_DATA') + + row = layout.row() + row.label(text="Active object is: " + obj.name) + row = layout.row() + row.prop(obj, "name") + + row = layout.row() + row.operator("mesh.primitive_cube_add") + + + def register(): + bpy.utils.register_class(HelloWorldPanel) + + + def unregister(): + bpy.utils.unregister_class(HelloWorldPanel) + + + if __name__ == "__main__": + print("Hello World: run from Blender Text Editor") + else: + print("Hello World: run from VSCode") + print(f"NOTE. __name__ is : {__name__}") + + register() + + + .. tip:: + + Although blender has builtin the python modules for bpy, it is a good practice to install the "fake-bpy-module" in your local python environment. + This will allow VSCode to provide autocompletion and other features. You can install it by running the following command in the VSCode terminal: + + .. code-block:: + + python3.11 -m pip install fake-bpy-module-latest + + + .. image:: images/install-bpy-fake-windows.png + :width: 1000 px + + + We have changed the last part of the script since running from VSCode has some subtle differences compared to running from the Blender Text Editor. In particular the special variable `__name__` is different. + + - Press CTRL-SHIFT-P and type "Blender: Open Scripts Folder". Select the previous folder where the script file is located + - Press CTRL-SHIFT-P and type "Blender: Start". Blender will start. + - Press CTRL-SHIFT-P and type "Blender: Run Script". The script will run and the output will be seen in Blender! + + As you can see below. We have set a break-point in line 37 (see point 13 below for another example of setting a break-point). We can inspect in the left side the local variables, global variables, add watches, + check the stack, etc. For example we can see that __name__ has a value of "" Instead of "__main__". + + .. image:: images/script-blender-vscode.png + :width: 1000 px + + + Once we continue execution we can check in the VSCode Terminal the output and in Blender the panel created by the script. + + .. image:: images/script-blender-vscode-2.png + :width: 1000 px + + + CONGRATULATIONS! You have now a development environment ready to speedup your python scripting in Blender. + + +X. **BONUS: Editing Bonsai Documentation**: Please refer to `Writing documentation `__ for details on how to edit and contribute documentation. + Here we just summarize the steps to integrate that workflow in VSCode and using Inkscape. + + - Download and install Inkscape from `Inkscape download page `__. In our case we will use `Inkscape 1.4 Windows 64 bit msi installer `__. + + - The file below has the style annotation for the Bonsai documentation. + + .. container:: blockbutton + + `Download style annotation file `__ + + It contains some shapes and styles that you can use to create your own diagrams. + + .. image:: images/inkscape-annotation-template.png + :width: 1000 px + + - Open some screenshot file you want to add annotations in Inkscape and also open this template. You can then copy paste from the template to the screenshot file. + + .. warning:: + When copying the shapes for your convenience just make sure that you do not have selected the option "When scaling objects, scale the stroke width by the same proportion" + to keep the style width right as per Bonsai documentation style guidelines + + .. image:: images/inkscape-scaling-outline.png + :width: 1000 px + + - Once done you can export your edited screenshot as PNG to be used in the docummentation. :menuselection:`File --> Export...` and click in the Export button on bottom right corner. + - As described in `Writing documentation `__ you need to have sphinx installed in your system. One of the easiest ways is to use `Chocolately `__. + Install Chocolately and then you can simply run the following command in the terminal: + + .. code-block:: + + choco install sphinx + + and then install the theme and theme dependencies: + + .. code-block:: + + python3.11 -m pip install furo + python3.11 -m pip install sphinx-autoapi + python3.11 -m pip install sphinx-copybutton + + All these can be accomplished within a terminal of VSCode. + + .. image:: images/doc-pip-furo.png + :width: 1000 px + + + - To speedup your workflow you can add the following VSCode files in the .vscode folder of your cloned repository. In our case it is *C:\\Users\\falke\\Documents\\bonsaiDevel\\IfcOpenShell\\.vscode* + - Make sure to edit them with the right paths in your system. + + - `launch.json `__ + + .. image:: images/launch-windows-jason.png + :width: 1000 px + + - `tasks.json `__ + + .. image:: images/tasks-windows-jason.png + :width: 1000 px + + - Now you can use the debug tool in VSCode to regenerate the html documentation by cliking the "Play" button *BonsaiDocsServer (IfcOpenShell)* in the top left corner of the debug tool. + + .. image:: images/bonsai-doc-server.png + :width: 1000 px + + - Once the server is started you can open a browser and go to the following URL: + http://localhost:8000/ and you will see the documentation. + + - In order to rebuild the documentation you need to stop the server and run the command again. You can do this by clicking in the "Abort" button in the bottom right corner of the debug tool. + + .. image:: images/doc-server-running.png + :width: 1000 px + + CONGRATULATIONS! And happy documenting! + + + +Now let's find out how to interact with GitHub in order to make changes to the Bonsai project. + + +7. **Install GitHub related VSCode extensions**: To facilitate the use of git commands and pulling + and pushing files from a local repository towards github, please install as well the following VSCode + extensions: + + - GitHub Pull Requests + - GitHub Repositories + - Remote Repositories + + Optionaly you can also install Copilot extensions + + - GitHub Copilot + - GitHub Copilot Chat + + .. image:: images/VSCode-extensions.png + :width: 500 px + + +8. **Fork IfcOpenShell project from GitHub**: For this step you will need an account on GitHub. + Once you have a registered account you can find it under https://github.com/YOURGITHUBUSERID + In the example for *falken10vdl* the link is https://github.com/falken10vdl + + .. image:: images/GitHubUser.png + :width: 1000 px + + Go to the `IfcOpenShell GitHub page `__. And + click on the Fork button. Please make sure that you are logged with your GitHub account as shown in the + top right corner of the page. + + .. image:: images/fork-bonsai.png + :width: 1000 px + + Once the fork is generated you will be redirected to your own fork of the IfcOpenShell project. + + .. image:: images/forked-bonsai.png + :width: 1000 px + + Now we will clone the forked repository to our local machine. + +9. **Clone bonsai to our development environment**: Launch VSCode + Select the Source Control tool. Then :menuselection:`Clone repository` and then select "Clone from GitHub". + + .. image:: images/cloning-from-github.png + :width: 1000 px + + A series of steps will be required to authenticate with GitHub. You will need to provide your GitHub credentials. + Once VSCode has authenticated yourself in GitHub, you will be able to select the repository you want to clone. + In this case we will clone the IfcOpenShell repository. + + .. image:: images/selecting-forked-repo.png + :width: 1000 px + + VSCode will ask you to select a folder where the repository will be cloned. and it will start the cloning process. + + Once finished, you will see the repository in the Explorer tool. + + .. image:: images/cloned-repo.png + :width: 1000 px + +10. **Link the Bonsai addon to the local cloned repository**: We will now edit the following + script that establishes links from the unstable-installation to the cloned repository so we + can easily see the changes done in the cloned repository taken effect when we load blender + locally. + + .. container:: blockbutton + + `Download dev_environment.bat `__ + + Edit the file to match the paths in your system. In our case we will edit the following lines: + + - SET REPO_PATH=%HOMEDRIVE%\\Users\\%USERNAME%\\Documents\\bonsaiDevel\\IfcOpenShell + - SET BLENDER_PATH=%HOMEDRIVE%\\Users\\%USERNAME%\\AppData\\Roaming\\Blender Foundation\\Blender\\4.2 + - SET PACKAGE_PATH=%BLENDER_PATH%\\extensions\\.local\\lib\\python3.11\\site-packages + - SET BONSAI_PATH=%BLENDER_PATH%\\extensions\\raw_githubusercontent_com\\bonsai + + You need to run it as an administrator. + + .. image:: images/run-as-administrator.png + :width: 1000 px + + Confirm the data and the script will create the necessary links. + + .. image:: images/running-dev_environment-bat.png + :width: 1000 px + + + .. warning:: + + If you receive errors like this: + + .. code-block:: bash + + The system cannot find the path specified. + + It means that you have not installed the Bonsai Blender extension. Please refer to tha + last part of point 2. above and follow the `Unstable installation `__. + + +11. **Adjust the VSCode Blender extension**: We will now make some adjustments to the VSCode Blender extension to ease the reload of the addon. + Select the Extensions tool. Then :menuselection:`Blender Development` and then select :menuselection:`Settings`. + + .. image:: images/VSCode-blender-extension-settings.png + :width: 1000 px + + Click twice in "Add Item" within the *Blender: Additonal Arguments* section and add the following two items (adapt *Testing.ifc* to the name of the IFC file you want to + test during Bonsai development): + + - --python-expr + - import bpy; import os; os.chdir("C:\\\\Users\\\\falke\\\\Documents\\\\blender-4.2.8-windows-x64"); bpy.ops.bim.load_project(filepath="C:\\\\Users\\\\falke\\\\Documents\\\\bonsaiDevel\\\\Testing.ifc", should_start_fresh_session=True, use_detailed_tooltip=True) + + .. image:: images/VSCode-blender-additional-arguments-windows.png + :width: 1000 px + + .. Note:: + + You can use double backslash (\\\\) and double quotes (") in the path for correct interpretation by VSCode or you can use single forward slash + (/) and single quotes (') as well. In this case the path will be: 'C:/Users/falke/Documents/bonsaiDevel/Testing.ifc' + + .. image:: images/VSCode-blender-additional-arguments-2-windows.png + :width: 1000 px + + + Make sure that Blender > Addon: Just My code is not selected (This allows to set the breakpoints anywhere in the source code). + + .. image:: images/just-my-code-false.png + :width: 1000 px + + + .. warning:: + + This way to use the VSCode Blender extension is not the standard one. Refer to the `VSCode Blender extension documentation `__ for the standard way to use it. + The reason behind is that this allows us to start VSCode in the top of the cloned repository so + all the Git related funtionality in VSCode works properly and we have a complete view from VSCode + :menuselection:`Explorer` tool of the whole repository. + + Bonsai is a big project with a lot of dependencies + so reloading it is not an easy task (see discussion in https://community.osarch.org/discussion/1650/vscode-and-jacquesluckes-blender-vscode/p1). We have taken the pragmatic approach to start blender with a specific file (*Testing.ifc*) + and then we can reload the addon from the Blender UI which also uploads automatically the changes in the addon and the testing file + + To summarize: + + - We need *Blender > Addon: Just My code* to get the breakpoint functionality even if the addon is not "registered/loaded" to the extension (due to the root folder we use) + - We need *Blender: Additonal Arguments* to automatically load the Testing.ifc file when we start Blender from VSCode (We do not use *Blender:Reload Addons* since it does not work in our case) + + Instead of restarting Blender from VSCode, we use the Blender UI that, as explainedin the next step, it provides a simple way to get the addon and the Testing file reloaded. + +12. **Launch blender from VSCode**: We are now ready to launch Blender from VSCode. + Open VSCode. Open the cloned repository if not already open. + Press CTRL-SHIFT-P and type "Blender: Start". + + .. image:: images/VSCode-blender-start.png + :width: 1000 px + + Blender will start loading the Testing.ifc file. You can now start exploring the code and make changes to the addon! + + .. image:: images/VSCode-and-blender.png + :width: 1000 px + + In order to be able to restart blender (and reload the addons + reload the Testing file) we need to + enable "Developer Extras" and also a good practice is to enable "Python Tooltips" in :menuselection:`Edit --> Preferences --> Interface`. + + .. image:: images/enable-developer-extras.png + :width: 500 px + + Once these are enabled, you can press F3 and write "restart" to restart Blender. + + .. image:: images/restart-blender.png + :width: 1000 px + + + .. warning:: + The Windows conpty Dll will force the terminal to be detached once Blender is restarted and you will lose the console output. + In order to avoid that, you can enable the following settings in VSCode: + + Go to :menuselection:`File --> Preferences --> Settings` and search for "terminal.integrated.windows". Enable both *terminal.integrated.windowsEnableConpty* + and *terminal.integrated.windowsUseConptyDll*. + + .. image:: images/terminal-integrated-windows.png + :width: 1000 px + + - *terminal.integrated.windowsEnableConpty* makes it possible to restart blender from Bonsai restart_blender command. + + - *terminal.integrated.windowsUseConptyDll* makes it possible to maintain the console attached so the output of the reloaded blender instance is still visible in the terminal. + + .. note:: + + Once you enable "Developer Extras" you will see that you can right click in the UI and select "Source Code" to see the code behind the UI. For example in the image below you can + right click in the "Generate SVG" and select "Edit Source". + + .. image:: images/edit_source.png + :width: 1000 px + + Then in the "Scripting" tab you can click and select a new editor windows that has been created (in this case it is called "uy.py"). + + .. image:: images/scripting_ui_code.png + :width: 500 px + + If you select it, you will see the relevant code with a vertical blue line marking the exact point in the source code where the UI element is defined. + + .. image:: images/marked_code.png + :width: 1000 px + + From there it is quite usefull to search in VSCode to find the relevant file within the Bonsai source code. For that you can go to :menuselection:`Edit --> Find in Files`. + + .. image:: images/vscode_search_in_files.png + :width: 350 px + + Then you can click in the results to get the file opened in the editor. + + .. image:: images/vscode_search_results.png + :width: 1000 px + + + .. tip:: + + Once you enable "developer Extras" you will be able to select in :menuselection:`Edit --> Preferences --> Experimental --> Debugging` a number of options related to code development. + + .. image:: images/blender_experimental_debugging.png + :width: 500 px + + In the case case of Bonsai. You have the TAB :menuselection:`Quality & Coordination --> Debug --> Experimental --> Debugging` that also provides a number of tools to ease the development process. + + .. image:: images/bonsai_debug.png + :width: 500 px + + Finally, there are a number of usefull Blender addons that can also help you in the development process. For example "Icon Viewer" or "Math vis". + + .. image:: images/blender_development_addons.png + :width: 500 px + + +13. **Add a break-point**: Let's add a break-point in the code to see how it works. + Press CTRL-SHIFT-P and type "Blender: Start". Blender will start. + Open the cloned folder and go to *src > bonsai > bonsai > bim > module > light > prop.py* and go to line 75. + Add a line for a print statement and click on the left side of the line number to add a break-point. + + .. code-block:: python + + 74 def update_shadow_mode(self, context): + 75 print("Shadow mode", self.shadow_mode) + 76 if self.shadow_mode == "SHADING": + + + Set a break-point in line 75. + + .. image:: images/break-point.png + :width: 1000 px + + In Blender. Go To SOLAR ANALYSIS Tool in Bonsai and Click in "No Shadow", "Shaded" or "Rendered" + + .. image:: images/trigger-breakpoint.png + :width: 1000 px + + + This will trigger the break-point. See how the execution is stopped at the break-point. + + .. image:: images/break-point-stop.png + :width: 1000 px + + + Click in the debugging tools the option for "step over" (F10). + + .. image:: images/step-over.png + :width: 1000 px + + You can see the print statement executed and the output in the VSCode internal terminal. + + .. image:: images/print-to-console.png + :width: 1000 px + + + From here you can watch the local variables, global variables, add watches, check the stack, etc. + Resume execution or move step by step to see how the code is executed. + + CONGRATULATIONS! You have now a development environment ready to explore the Bonsai code and contribute to the project. + +14. **Make changes and do a Pull Request to the project**: In the previous steps we got a complete IDE to explore and make changes to the Bonsai sourcecode. + In this step we will provide a simple workflow of using Git commands within VSCode to make changes and do a Pull Request to the project. + Bonsai changes very fast so our cloned repository will be outdated very soon. We propose to do the following: + + a. Check in our GitHub page if our project fork (https://github.com/falken10vdl/IfcOpenShell) is outdated compared to the IfcOpenShell main branch (https://github.com/IfcOpenShell/IfcOpenShell). + b. Sync our fork with the upstream branch (if needed). + c. Pull the changes in our porject fork to our local repository (/home/falken10vdl/bonsaiDevel). + d. Create a new branch in our local repository (example: *DOC_QS_IDE*) + e. Publish the branch to our project fork in GitHub. + f. Make changes in the code. + g. Commit the changes. + h. Push the changes to our project fork. + i. Create a Pull Request to the upstream main branch of the IfcOpenShell project. + + Let's see below the steps with an example of changing the documentation of the Quickstart guide for the IDE in Windows. + + a. Check in our GitHub page if our project fork is outdated. Click *Update branch* + + .. image:: images/check-fork.png + :width: 1000 px + + b. After clicking *Update branch* our fork is up to date with the upstream main branch. + + .. image:: images/sync-fork.png + :width: 1000 px + + c. Pull the changes in our project fork to our local repository + + .. image:: images/pull-changes.png + :width: 1000 px + + d. Create a new branch in our local repository by clicking in the current branch name in the bottom left corner of the VSCode window. Give a name to the branch and press Enter. + + .. image:: images/create-branch.png + :width: 1000 px + + The new branch is created and we can see it in the bottom left corner of the VSCode window. + + .. image:: images/new-branch-local.png + :width: 1000 px + + e. Publish the branch to our project fork in GitHub by clicking in the publish button (*little cloud with up arrow*) in the bottom + left corner of the VSCode window. Select as origin the project fork. + + .. image:: images/new-branch-publish-to-private-github.png + :width: 1000 px + + Check that the branch is now in our project fork in GitHub. + + .. image:: images/new-branch-in-private-github.png + :width: 1000 px + + f. Make changes in the code. In this case we will change documentation by adding a Quickstart for the IDE in Windows. :) + + .. image:: images/make-changes-windows.png + :width: 1000 px + + g. Commit the changes. + + First provide your user name and email to Git (this is required only once). + + .. image:: images/git-user-email-windows.png + :width: 1000 px + + Then commit the changes by clicking in the check mark in the Source Control tool. + + .. image:: images/commit-changes-windows.png + :width: 1000 px + + Accept the staging of the changes prior to commit. + + .. image:: images/staging-prior-commit.png + :width: 350 px + + h. Push the changes to our new branch in the github project fork. + + .. image:: images/push-to-private-fork-new-branch.png + :width: 1000 px + + Check that the changes are in the project fork in GitHub. You can see that the directory *ide* has been added, for example. + + .. image:: images/private-fork-new-branch-updated-windows.png + :width: 1000 px + + + i. Create a Pull Request to the upstream main branch of the IfcOpenShell project. + Go to your GitHub page and you will see that the new branch has 1 commit ahead of the upstream main branch. Click in the *Compare & pull request* button. + + .. image:: images/compare-and-pull-request.png + :width: 1000 px + + Verify that the changes are correct, add a description and click in the *Create pull request* button. + + .. image:: images/pull-request-windows.png + :width: 1000 px + + .. note:: + + If you need to update the Pull Request with new changes, you can do it by making the changes in the local repository and then commit and push them to the same branch. + The Pull Request will be updated automatically. You can also add comments to the Pull Request to explain the changes made. + + .. warning:: + + Sometimes the process of changing the initial code for the Pull Request takes enough time that already the upstream main branch has changed significately. This means that a direct merge to the upstream branch + is not possible without conflicts. In this case you will need to rebase the Pull Request branch with the upstream main branch.This takes all your commits from the current PR branch and reapplies them one by one on top of the latest commits + in the target branch (which should be the upstream main branch). This is a bit more complex process and you can refer to the `Using Git source control in VS Code `__ for more information. + + .. image:: images/rebase_branch.png + :width: 1000 px + + + CONGRATULATIONS! You have now made a change in the Bonsai project and created a Pull Request to the main branch of the project. Happy coding and documenting! + +15. **Test someone else's Pull Request**: Ofen times you want to provide feedback to someone else's Pull Request. + A simple way to do this is by using the GitHub Pull Request extension in VSCode. Please refer to `GitHub Pull Requests in Visual Studio Code `__ for more information. + + .. image:: images/checkout_pull_request_vscode.png + :width: 1000 px + + This will fetch the branch of the Pull Request and you will be able to test it as if you had created your own branch. + + .. image:: images/pull_request_see.png + :width: 1000 px + + You can also use the GitHub Pull Request extension to review the Pull Request and provide comments. And of course the rest of the VSCode functionality to test, debug, improve, etc. the code. + + CONGRATULATIONS! and happy testing! \ No newline at end of file