Build

Author: IfcOpenBot

CNAME

@@ -49,22 +49,22 @@ This section provides an overview of key IFC concepts and how they're implemente
 
       .. container:: card
 
-         :doc:`ifc_concepts/spatial_objects`
+         :doc:`spatial_objects`
             Basic spatial objects.
 
       .. container:: card
 
-         :doc:`ifc_concepts/classification_and_types`
+         :doc:`classification_and_types`
             IFC classification hierarchy and the concept of types and occurrences.
 
       .. container:: card
 
-         :doc:`ifc_concepts/geometry_and_representations`
+         :doc:`geometry_and_representations`
             Understanding IFC geometry, representations, and parametric materials.
 
       .. container:: card
 
-         :doc:`ifc_concepts/working_with_representations`
+         :doc:`working_with_representations`
             Representations in Bonsai.
 
 .. container:: global-index-toc
@@ -74,7 +74,7 @@ This section provides an overview of key IFC concepts and how they're implemente
       :caption: Understanding IFC
       :maxdepth: 2
 
-      ifc_concepts/spatial_objects
-      ifc_concepts/classification_and_types
-      ifc_concepts/geometry_and_representations
-      ifc_concepts/working_with_representations
+      spatial_objects
+      classification_and_types
+      geometry_and_representations
+      working_with_representations

_sources/guides/authoring/understanding_ifc.rst.txt

@@ -0,0 +1,21 @@
+Code style
+============
+
+
+Black code formatter
+-------------------------------
+For Python code formatting, we use `Black code formatter <https://pypi.org/project/black/>`__, 
+black settings are stored in the repository's pyproject.toml.
+
+We have GitHub workflow `ci-black-formatting` to maintain black formatting across the repository.
+
+``black`` can be installed using ``pip install black`` and files can be formatted with the following example command:
+
+.. code-block:: bash
+
+   # Format the entire repository.
+   # Should be used in 99% cases as the entire repository is already formatted using black.
+   black .
+   # Format only some specific file.
+   black src/bonsai/bonsai/bim/module/qto/operator.py
+

_sources/guides/development/code_style.rst.txt

@@ -0,0 +1,128 @@
+Debugging Bonsai
+================
+
+This is a mini-guide to setting up an IDE and configuring it to debug Bonsai
+more easily. It is currently specific to this writers own system (Ubuntu) but
+this can be expanded by others.
+
+1. **Install VSCode/VSCodium**: This will be system specific. I used the
+   available snap package.
+
+   .. code-block:: bash
+
+      sudo snap install --classic codium
+
+   I chose VSCodium to avoid Microsoft telemetry and data harvesting, but
+   VSCode is going to be similar, and even a bit easier (i.e. step 3).
+
+2. **Activate Python language support**: Start VSCode/VSCodium, open the
+   Extensions tab, find the Python language support and activate it.
+
+3. **Install Blender Addon**: This step depends on which IDE you chose.
+
+   a. VSCode
+
+      Open up the Extensions tab on the left, and search for the *Blender
+      Development* extension. Select it, and click Install.
+
+      I haven't actually tested this, but this should install the 
+      *ms-vscode.cpptools* dependancy for you. If not, you may need to search
+      for, and install, this extension too.
+
+   b. VSCodium
+
+      It seems VSCodium is not allowed to direct access the Marketplace, and
+      due to licensing it is not possible to install the *Blender Development*
+      extension because of the *ms-vscode.cpptools* dependancy.
+
+      VSCodium's equivalent Marketplace does not (and could not due to
+      licensing) provide a functioning *Blender Development* extension. (Or I'm
+      an idiot... entirely possible).
+
+      I've created an alternative *Blender Development* extension with the
+      *ms-vscode.cpptools* dependancy removed.
+
+      .. note::
+         This alternative should also work in VSCode, but you may as well save
+         yourself the hassle, and just use the original one.
+
+      Download the *Blender Development* ``.vsix`` file from my GitHub fork
+      using your browser from `this <https://github.com/sboddy/blender_vscode>`_
+      repository. The ``.vsix`` is available on the Releases page.
+
+      In VSCodium's Extensions sidebar install it with "**...**" ->
+      "**Install from VSIX...**"
+
+      If you are squeamish about downloading my ``.vsix``, you can review the
+      single commit, clone the repo and create your own.
+
+4. **Set the Blender config directory**: In **Settings** -> **Extensions** ->
+   **Blender** -> "**Environment Variables**"
+   edit the json file to set the ``BLENDER_USER_RESOURCE`` to the config folder
+   you installed Bonsai to. *For me*:
+
+   .. code-block:: json
+
+      {
+         "blender.environmentVariables": {
+            "BLENDER_USER_RESOURCES": "/home/steve/.config/blender/4.2bonsai"
+         }
+      }
+
+   .. warning::
+      You `must` change that path to the correct value for your system.
+
+5. **Unset the Just My Code flag**:  In **Settings** -> **Extensions** ->
+   **Blender** -> "**Just My Code**" by unchecking the box.
+
+   Again, this was advice found searching around in a github issue. If not
+   done, the breakpoints do not work for me.
+
+6. **Open the folder in VSCode/VSCodium**: This is the same folder set in step
+   5. Again, *for me*:
+
+   ``/home/steve/.config/blender/4.2bonsai``
+
+   This was a key point for me. Do `not` go deeper in the folder structure -
+   that just doesn't work. (Thanks @theoryshaw) This feels a little like
+   using a sledgehammer to crack a nut, and there might be a better, "proper"
+   way of setting this up. If there is I'd love to hear it.
+
+7. **Start Blender**: In VSCode/VSCodium press ``Ctrl+Shift+P``, and
+   search/select **Blender: Start**.
+
+8. **Set the Blender binary path**: The first time you try to start Blender the
+   addon will ask for the path of the binary. Navigate to your Blender binary
+   and select it. *For me*:
+
+   ``/home/steve/Software/blender-git/build_linux/bin/blender``
+
+   .. warning::
+      Do `not` try to use a binary installed using snap - it will `not` work.
+      Either install a debian package of Blender, or build it from source, and
+      use that.
+
+   All being well, Blender should start and show the usual Bonsai UI.
+
+9. **Ensure Blender is behaving**: Exercise the interface a bit to be sure
+   Bonsai is working normally. Add a demo project, add some walls, etc.
+
+   One issue I ran in to was opening the wrong folder in step 7. Due to the
+   way VSCode/VSCodium works, I was getting two Bonsai plugins conflicting,
+   and failing in interesting ways. One symptom of this was the modal user
+   interface when adding walls was completely missing. Oh, and the debugger
+   completely failed to work.
+
+   If you are happy, quit Blender, and try setting some breakpoints in
+   VSCode/VSCodium then run Blender again, and try to trigger them. I set one
+   on the ``bim.add_sheet`` operator at:
+   ``extensions/.local/lib/python3.11/site-packages/bonsai/bim/module/drawing/operator.py:1456``
+
+   .. note::
+      I made the mistake of setting the breakpoint on the ``_execute``
+      methods ``def`` line, which did not work. This probably helped confuse
+      me when trying to get the addon to work.
+
+If you get to this point, congratulations! You will now be 1000% more effective
+when troubleshooting issues, and able to make many more contributions, fixes
+and patches.

_sources/guides/development/debugging.rst.txt

@@ -0,0 +1,28 @@
+Getting Started
+===============
+
+Bonsai is an open-source project, and its development is driven by the contributions of a dedicated community of developers,
+architects, engineers, and enthusiasts. If you're interested in contributing to the project, whether by submitting bug reports,
+suggesting new features, or contributing code, your involvement is highly encouraged and appreciated.
+
+This part of the documentation covers various aspects of the Bonsai development process, including:
+
+- :doc:`Writing User Documentation </contribute/writing_docs>`
+- :doc:`Translations and Internationalisation </contribute/translations>`
+- Contributing Code
+    - :doc:`Installation and Setting up a Development Environment </guides/development/installation>`
+    - Understanding the Project Structure and Codebase
+        - :doc:`Hello, World! </guides/development/hello_world>`
+        - :doc:`Undo System </guides/development/undo_system>`
+    - :doc:`Code Style Guidelines and Best Practices </guides/development/code_style>`
+
+..
+    - :doc:`Submitting Pull Requests and Contributing Code </guides/development/contributing_code>`
+
+- :doc:`Testing and Quality Assurance </guides/development/running_tests>`
+- :doc:`System Support and Multiplatform Compatibility </guides/development/installation>`
+- :doc:`User Experience and User Interface Guidelines </guides/development/ux_guidelines>`
+
+The Bonsai Developer Documentation is a living resource maintained by the core development team and the open-source community. It serves as a central hub for developers who want to get involved in the project, ensuring a consistent and efficient development process.
+
+By contributing to Bonsai, you'll not only be helping to improve and expand the capabilities of this powerful open-source BIM authoring platform but also be part of a vibrant community driving innovation in the AEC industry.

_sources/guides/development/getting_started.rst.txt

@@ -15,3 +15,4 @@ This chapter covers how you can help contribute to Bonsai.
       translations
       undo_system
       writing_docs
+      debugging

_sources/guides/development/index.rst.txt

@@ -102,11 +102,17 @@ that they are typically updated every day. To install the **Unstable** version:
    .. image:: images/unstable-restart.png
 
 If you wish to install an **Unstable** version offline, you can download a
-daily build from the `GitHub releases page
+daily or previous build from the `GitHub releases page
 <https://github.com/IfcOpenShell/IfcOpenShell/releases?q=bonsai&expanded=true>`__,
 then go to :menuselection:`Topbar --> Edit --> Preferences --> Get Extensions
 --> "V" Icon (top right) --> Install from Disk`.
 
+.. tip::
+
+   Installing a previous build is a great way to roll back to previous versions. Uninstall the current version, 
+   then install the previous version from your disk. Make the install directory into the repo folder, and you can still 
+   update by the click of a button, when you are ready for the latest build.
+
 Bundling for Blender
 --------------------
 
@@ -153,25 +159,31 @@ our Blender installation (you will need to restart Blender to see changes).
 
 For Linux or Mac:
 
-.. literalinclude:: ../../scripts/installation/dev_environment.sh
+.. literalinclude:: ../../../scripts/installation/dev_environment.sh
    :language: bash
    :caption: dev_environment.sh
 
 Or, if you're on Windows, you can use the batch script below. You need to run
 it as an administrator. Before running it follow the instructions descibed
 in the `rem` tags.
 
-.. literalinclude:: ../../scripts/installation/dev_environment.bat
+.. literalinclude:: ../../../scripts/installation/dev_environment.bat
    :language: bat
    :caption: dev_environment.bat
 
 After you modify your code in the Git repository, you will need to restart
 Blender for the changes to take effect.
 
+If there are changes to the IfcOpenShell binaries, you may replace the two
+``*ifcopenshell_wrapper*`` files with new ones downloaded from the automated
+`IfcOpenShell builds directory <https://builds.ifcopenshell.org/>`__.
+
 The downside with this approach is that if a new dependency is added, or a
-compiled dependency version requirement has changed, or the build system
-changes, you'll need to fix your setup manually. But this is relatively rare.
-Reviewing the Makefile history, `here <https://github.com/IfcOpenShell/IfcOpenShell/commits/v0.8.0/src/bonsai/Makefile>`__, is one quick way to see if a dependency has changed.  
+compiled dependency has changed (that is not available via the build
+directory), or the build system changes, you'll need to fix your setup
+manually. But this is relatively rare. Reviewing the Makefile history, `here
+<https://github.com/IfcOpenShell/IfcOpenShell/commits/v0.8.0/src/bonsai/Makefile>`__,
+is one quick way to see if a dependency has changed.
 
 .. seealso::