From 2789bc565a7c9ef3cf06a62c54021c1c23a0a978 Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Thu, 9 May 2024 16:21:24 +1000 Subject: [PATCH] Write troubleshooting documentation --- src/blenderbim/blenderbim/__init__.py | 2 +- src/blenderbim/blenderbim/bim/ui.py | 12 +- src/blenderbim/docs/devs/installation.rst | 6 +- src/blenderbim/docs/index.rst | 1 + .../docs/users/images/error-message.png | Bin 0 -> 9425 bytes src/blenderbim/docs/users/installation.rst | 123 +++++------------- src/blenderbim/docs/users/troubleshooting.rst | 93 +++++++++++++ 7 files changed, 141 insertions(+), 96 deletions(-) create mode 100644 src/blenderbim/docs/users/images/error-message.png create mode 100644 src/blenderbim/docs/users/troubleshooting.rst diff --git a/src/blenderbim/blenderbim/__init__.py b/src/blenderbim/blenderbim/__init__.py index c5d6420273..e54b2d04ac 100644 --- a/src/blenderbim/blenderbim/__init__.py +++ b/src/blenderbim/blenderbim/__init__.py @@ -131,7 +131,7 @@ if sys.modules.get("bpy", None): box.label(text=f"Python {py} BBIM {info['blenderbim_version']}", icon="SCRIPTPLUGINS") layout.operator("bim.copy_debug_information", text="Copy Error Message To Clipboard") op = layout.operator("bim.open_uri", text="How Can I Fix This?") - op.uri = "https://docs.blenderbim.org/users/installation.html#faq" + op.uri = "https://docs.blenderbim.org/users/troubleshooting.html#installation-issues" class OpenUri(bpy.types.Operator): bl_idname = "bim.open_uri" diff --git a/src/blenderbim/blenderbim/bim/ui.py b/src/blenderbim/blenderbim/bim/ui.py index 7654062959..2b55904929 100644 --- a/src/blenderbim/blenderbim/bim/ui.py +++ b/src/blenderbim/blenderbim/bim/ui.py @@ -29,8 +29,9 @@ from ifcopenshell.util.doc import ( get_attribute_doc, ) from . import ifc -import blenderbim.tool as tool +from blenderbim import get_debug_info import blenderbim.bim +import blenderbim.tool as tool from blenderbim.bim.helper import IfcHeaderExtractor from blenderbim.bim.prop import Attribute @@ -402,6 +403,15 @@ class BIM_PT_tabs(Panel): row = self.layout.row(align=True) row.prop(aprops, "tab", text="") + + if blenderbim.last_error: + box = self.layout.box() + box.label(text="BlenderBIM experienced an error :(", icon="ERROR") + box.label(text="View the console for full logs.", icon="CONSOLE") + box.operator("bim.copy_debug_information", text="Copy Error Message To Clipboard") + op = box.operator("bim.open_uri", text="How Can I Fix This?") + op.uri = "https://docs.blenderbim.org/users/troubleshooting.html" + except: pass # Prior to load_post, we may not have any area properties setup diff --git a/src/blenderbim/docs/devs/installation.rst b/src/blenderbim/docs/devs/installation.rst index 96ee05e206..bda42056bc 100644 --- a/src/blenderbim/docs/devs/installation.rst +++ b/src/blenderbim/docs/devs/installation.rst @@ -13,9 +13,9 @@ Unstable installation **Unstable installation** is almost the same as **Stable installation**, except that they are typically updated every day. Simply download a daily build from -the `Github releases page -`__, then follow the same -instructions as the **Stable installation**. +the `GitHub releases page +`__, then follow the +usual :doc:`installation instructions`. You will need to choose which build to download. diff --git a/src/blenderbim/docs/index.rst b/src/blenderbim/docs/index.rst index b8f21e5a6b..7d6b439721 100644 --- a/src/blenderbim/docs/index.rst +++ b/src/blenderbim/docs/index.rst @@ -32,6 +32,7 @@ Learn how to model a small building and create simple architectural plans, secti users/git_support users/other_addons users/general_usage + users/troubleshooting .. toctree:: :hidden: diff --git a/src/blenderbim/docs/users/images/error-message.png b/src/blenderbim/docs/users/images/error-message.png new file mode 100644 index 0000000000000000000000000000000000000000..bdc1ce38f0573733a69111c949fa86c2336cf3ae GIT binary patch literal 9425 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 XZFNAQRE~j_GHA+*8n3G4Ek6D)bmTzE literal 0 HcmV?d00001 diff --git a/src/blenderbim/docs/users/installation.rst b/src/blenderbim/docs/users/installation.rst index 95a6099913..bbcd8fe7c8 100644 --- a/src/blenderbim/docs/users/installation.rst +++ b/src/blenderbim/docs/users/installation.rst @@ -58,51 +58,6 @@ You can enable add-ons permanently by using ``Save User Settings`` from the Addo .. _where is the add-on installed: -Where is the add-on installed? ------------------------------- - -Upon installation, the BlenderBIM Add-on is stored in the -``scripts/addons/blenderbim/`` directory, within your Blender configuration -folder. However, the location of your Blender configuration folder depends on -how you have installed Blender. - -If you downloaded Blender as a ``.zip`` file without running an installer, you -will find the Blender configuration folder in the following directory, where -``X.XX`` is the Blender version: -:: - - /path/to/blender/X.XX/ - -Otherwise, if you installed Blender using an installation package, the Blender -configuration folder depends on which operating system you use. - -On Linux, if you are installing the add-on as a user: -:: - - ~/.config/blender/X.XX/ - -On Linux, if you are deploying the add-on system-wide (this may also depend on -your Linux distribution): -:: - - /usr/share/blender/X.XX/ - -On Mac, if you are installing the add-on as a user: -:: - - /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/ - -On Mac, if you are deploying the add-on system-wide: - -:: - - /Library/Application Support/Blender/X.XX/ - -On Windows: -:: - - C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\ - Updating -------- @@ -129,66 +84,52 @@ installed>`. If you do not restart Blender, the add-on will fail to remove correctly, and you will need to uninstall manually. +Where is the add-on installed? +------------------------------ -FAQ ---- +Upon installation, the BlenderBIM Add-on is stored in the +``scripts/addons/blenderbim/`` directory, within your Blender configuration +folder. However, the location of your Blender configuration folder depends on +how you have installed Blender. -If you are unable to install the BlenderBIM Add-on, make sure you are using -**Blender 4.1** installed from https://blender.org/ and are installing the -latest version from https://blenderbim.org. +If you downloaded Blender as a ``.zip`` file without running an installer, the +BlenderBIM Add-on will be installed in the following directory, where ``X.XX`` +is the Blender version: -Other common solutions are listed below. If none of these fix the problem, you -can `report a bug `_ or -`live chat with a developer `_. +:: -1. **Some other error prevents me from installing or doing basic functions with - the add-on. Is it specific to my environment?** + /path/to/blender/X.XX/scripts/addons/blenderbim/ - Try installing and using the BlenderBIM Add-on on a "clean environment". A - clean environment is a fresh Blender installation with no other add-ons - enabled with factory settings. +Otherwise, if you installed Blender using an installation package, the Blender +configuration folder depends on which operating system you use. - To quickly test in a clean environment, find your Blender configuration - folder based on the `where is the add-on installed`_ section. Rename the - folder from ``X.XX`` to something else like ``X.XX_backup``, then restart - Blender and try follow the installation instructions again. +On Linux, if you are installing the add-on as a user: - If this fixes your issue, consider disabling other add-ons one by one until - you find a conflict as a next step to isolating the issue. +:: -2. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.10'"** + ~/.config/blender/X.XX/scripts/addons/blenderbim/ - If you are using a Mac, be sure to use the Mac Silicon version if you have a - newer Mac. The only exception is if you have installed Blender using Steam - on a Mac, in which case you need to use the Mac Intel download. +On Linux, if you are deploying the add-on system-wide (this may also depend on +your Linux distribution): - For all other scenarios, check the BlenderBIM Add-on zip file which you - downloaded. The zip will have either ``py39``, ``py310``, or ``py311`` in - the name. See the instructions in the :ref:`devs/installation:unstable - installation` section to check that you have installed the correct version. +:: -3. **I am on Ubuntu and get an error similar to "ImportError: - /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"** + /usr/share/blender/X.XX/scripts/addons/blenderbim/ - Our latest package which uses IfcOpenShell v0.7.0 is built using Ubuntu 20 LTS. - If you have an older Ubuntu version, you can either upgrade to 19.10 or above, - or you'll need to compile IfcOpenShell yourself. +On Mac, if you are installing the add-on as a user: -4. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**" +:: - If you have installed Blender from another source instead of from - `Blender.org `__, such as from your - distro's package repositories, then you may be missing some modules like - ``numpy``. Try installing it manually like ``apt install python-numpy``. + /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/scripts/addons/blenderbim/ -5. **I get an error similar to RuntimeError: Instance #1234 not found** +On Mac, if you are deploying the add-on system-wide: - Blender saves and loads projects to a ``.blend`` file. However. the - BlenderBIM Add-on works with native IFC, and this means instead of saving - and loading ``.blend`` files, you should instead save and load the ``.ifc`` - project. +:: - If you have opened a ``.blend`` file, there is a risk that the contents of - the ``.blend`` session do not correlate to the contents of the ``.ifc``, - which can cause this error. Unless you are an advanced user, only save and - load ``.ifc`` files. + /Library/Application Support/Blender/X.XX/scripts/addons/blenderbim/ + +On Windows: + +:: + + C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\scripts\addons\blenderbim\ diff --git a/src/blenderbim/docs/users/troubleshooting.rst b/src/blenderbim/docs/users/troubleshooting.rst new file mode 100644 index 0000000000..0115bc5d27 --- /dev/null +++ b/src/blenderbim/docs/users/troubleshooting.rst @@ -0,0 +1,93 @@ +Troubleshooting +=============== + +The BlenderBIM Add-on is alpha software. There are many bugs! When something +goes wrong, you may see some computer code flash up on your screen. You may +also see an error message: + +.. image:: images/error-message.png + +**Don't panic!** Click on the button that says **Copy Error Message To +Clipboard**. You will need to paste this text in a bug report. + +If you do not have a GitHub account, you will need to sign up to report a bug. +In addition to pasting the error message text, please also describe what you +were doing, and attach your IFC file or screenshots if relevant. + +.. container:: blockbutton + + `Report a bug `__ + +If your issue is particularly complex, you can also chat live with developers +or other powerusers. + +.. container:: blockbutton + + `Chat live with a developer `_ + +Installation issues +------------------- + +If you are unable to install the BlenderBIM Add-on, make sure you are using +**Blender 4.1** installed from https://blender.org/ and are installing the +latest version from https://blenderbim.org. + +Other common solutions are listed below. If none of these fix the problem, you +can `report a bug `_ or +`live chat with a developer `_. + +1. **Some other error prevents me from installing or doing basic functions with + the add-on. Is it specific to my environment?** + + Try installing and using the BlenderBIM Add-on on a "clean environment". A + clean environment is a fresh Blender installation with no other add-ons + enabled with factory settings. + + To quickly test in a clean environment, first :ref:`find your Blender + configuration folder`. + Rename the folder from ``X.XX`` to something else like ``X.XX_backup``, then + restart Blender and try follow the :doc:`installation + instructions` again. + + If this fixes your issue, consider disabling other add-ons one by one until + you find a conflict as a next step to isolating the issue. + +2. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.10'"** + + If you are using a Mac, be sure to use the Mac Silicon version if you have a + newer Mac. The only exception is if you have installed Blender using Steam + on a Mac, in which case you need to use the Mac Intel download. + + For all other scenarios, check the BlenderBIM Add-on zip file which you + downloaded. The zip will have either ``py39``, ``py310``, or ``py311`` in + the name. See the instructions in the :ref:`devs/installation:unstable + installation` section to check that you have installed the correct version. + +3. **I am on Ubuntu and get an error similar to "ImportError: + /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"** + + Our latest package which uses IfcOpenShell v0.7.0 is built using Ubuntu 20 LTS. + If you have an older Ubuntu version, you can either upgrade to 19.10 or above, + or you'll need to compile IfcOpenShell yourself. + +4. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**" + + If you have installed Blender from another source instead of from + `Blender.org `__, such as from your + distro's package repositories, then you may be missing some modules like + ``numpy``. Try installing it manually like ``apt install python-numpy``. + +Common issues +------------- + +1. **I get an error similar to RuntimeError: Instance #1234 not found** + + Blender saves and loads projects to a ``.blend`` file. However. the + BlenderBIM Add-on works with native IFC, and this means instead of saving + and loading ``.blend`` files, you should instead save and load the ``.ifc`` + project. + + If you have opened a ``.blend`` file, there is a risk that the contents of + the ``.blend`` session do not correlate to the contents of the ``.ifc``, + which can cause this error. Unless you are an advanced user, only save and + load ``.ifc`` files.