Continuing work to update docs

src/bonsai/docs/_static/custom.css

@@ -83,6 +83,14 @@ img.icon {
     font-size: small;
     color: #808080;
 }
+span.menuselection {
+    border: 1px solid var(--color-admonition-title);
+    background-color: var(--color-admonition-title-background);
+    color: var(--color-admonition-text);
+    border-radius: 5px;
+    padding-left: 3px;
+    padding-right: 3px;
+}
 
 
 

src/bonsai/docs/index.rst

@@ -52,15 +52,11 @@ and data-rich OpenBIM with Blender :)
       :caption: Guides
       :maxdepth: 2
 
-      guides/viewing/index
-      guides/authoring/index
-      guides/drawings/index
-      guides/structural_analysis/index
-      guides/services/index
-      guides/costing_and_scheduling/index
-      guides/facility_management/index
-      guides/coordination/index
+      guides/viewing/dealing_with_large_models
+      guides/authoring/georeferencing
+      guides/authoring/git_support
       guides/development/index
+      guides/authoring/other_addons
       guides/troubleshooting
 
    .. toctree::
@@ -70,7 +66,6 @@ and data-rich OpenBIM with Blender :)
 
       reference/interface
       reference/topbar
-      reference/workspace
       reference/properties
 
 Need more help? Join the `live chat <https://osarch.org/chat/>`__ or `community

src/bonsai/docs/quickstart/create_model.rst

@@ -16,21 +16,21 @@ you will need to categorise your 3D elements (such as "Wall", "Column",
 Creating a single object
 ------------------------
 
-In the **Properties** panel on the right, ensure the icon for the **Scene
-Properties** tab is active showing the **Project Overview**. Click on **Create
-Project** to create a blank IFC project.
+Go to :menuselection:`Topbar --> File --> New IFC Project`, and select **New
+Metric (m) Project**. This will begin a blank IFC4 project.
 
 .. image:: images/create-project.png
 
-In the left **Outliner** panel, you will see a hierarchy of spaces that has
-been automatically created for you. This hierarchy is known is the **Spatial
-Tree**.
+In the :menuselection:`Properties --> Project Overview --> Spatial
+Decomposition` panel, you will see a hierarchy of spaces that has been
+automatically created for you. This hierarchy is known is the **Spatial Tree**.
 
 .. image:: images/default-spatial-tree.png
 
 There are many ways to create objects. In practice, you should use an element
 type library, and we will see how to do this later. For now, we will only add a
-single element. In the **Add** menu, add a cube.
+single element. In the :menuselection:`3D Viewport --> Add --> Mesh` menu, select
+**Cube**.
 
 .. image:: images/add-cube.png
 
@@ -45,10 +45,10 @@ Class**.
    Class**!
 
 Select the cube (selected objects are highlighted in orange, careful not to
-select anything else!) and switch to the **Object Information** tab. Let's
-pretend our Cube is a column, so select **IfcElement** from the **Products**
-dropdown, **IfcColumn** from the **Class** drop-down, and press **Assign IFC
-Class**.
+select anything else!) and switch to the :menuselection:`Properties --> Object
+Information` tab. Let's pretend our Cube is a column, so select **IfcElement**
+from the **Products** dropdown, **IfcColumn** from the **Class** drop-down, and
+press **Assign IFC Class**.
 
 .. image:: images/assign-class.png
 
@@ -58,19 +58,21 @@ Class**.
    the shape of your object. You can have a monkey-shaped wall if you want!
 
 All IFC objects must also belong inside the **Spatial Tree**. In the
-**Outliner** panel, you will see that your newly created **IfcColumn/Cube** has
-been automatically placed in **IfcBuildingStorey/My Storey**.
+:menuselection:`Properties --> Object Information --> Spatial Container` panel,
+you will see that your newly created **IfcColumn/Cube** has been automatically
+placed in **IfcBuildingStorey/My Storey**.
 
-.. image:: images/outliner-cube.png
+.. image:: images/cube-spatial-tree.png
 
-In the top left **File** menu, Save your new IFC model on your computer.
+Go to :menuselection:`Topbar --> File` and click **Save IFC Project** to save
+your new IFC model on your computer.
 
 .. image:: images/save-project.png
 
-Congratulations! You have now created your first OpenBIM model from Blender! You
-can open the IFC file in any other program, and you will see something similar
-to the image below. Three simple open source online viewers you can test with
-are `IfcPipeline <https://view.ifcopenshell.org>`__, `ThatOpenEditor
+Congratulations! You have now created your first IFC model with Bonsai! You can
+open the IFC file in any other program, and you will see something similar to
+the image below. Three simple open source online viewers you can test with are
+`IfcPipeline <https://view.ifcopenshell.org>`__, `ThatOpenEditor
 <https://platform.thatopen.com/app>`__, and `3DViewer
 <https://3dviewer.net/>`__.
 

src/bonsai/docs/quickstart/explore_model.rst

@@ -21,31 +21,33 @@ use some creativity when reading the data :)
 Loading a model
 ---------------
 
-Blender's interface is divided into three panels. The left **Outliner** panel
-shows a tree of geometric objects. The centre main **Viewport** panel shows 3D
-geometry. The right **Properties** panel shows data and relationships.
+Bonsai's interface is divided into three panels. The left
+:menuselection:`Outliner` panel shows geometric objects. The centre main
+:menuselection:`3D Viewport` panel shows 3D geometry. The right
+:menuselection:`Properties` panel shows data and relationships.
 
 .. image:: images/bonsai-layout.png
 
-The **Properties** panel has tabs to switch between different types of
-properties.
+The :menuselection:`Properties` panel has tabs to switch between different
+types of properties.
 
 .. image:: images/properties-tabs.png
 
-Click on ``File > Open IFC Project`` and browse to your ``.ifc`` file.
+Go to :menuselection:`Topbar --> File`, click **Open IFC Project**, and browse
+to your ``.ifc`` file.
 
 .. image:: images/properties-loadproject.png
 
-After loading, you will see the model appear in the **Viewport** panel.
+After loading, you will see the model appear in the :menuselection:`3D Viewport`.
 
 .. image:: images/example-project.png
 
-Take a look at the **Project Info** subpanel. It shows the loaded filename, as
-well as the **IFC Schema**. There are two commonly seen **IFC Schema**
-versions: IFC2X3 and IFC4. Checking the **IFC Schema** is important because it
-has an impact on what BIM data may be stored. IFC4 is the newer version and it
-is recommended to use IFC4 models as it has significantly more BIM capabilities
-compared to IFC2X3. 
+Take a look at the :menuselection:`Properties --> Project Overview --> Project
+Info` panel. It shows the loaded filename, as well as the **IFC Schema**. There
+are two commonly seen **IFC Schema** versions: IFC2X3 and IFC4. Checking the
+**IFC Schema** is important because it has an impact on what BIM data may be
+stored. IFC4 is the newer version and it is recommended to use IFC4 models as
+it has significantly more BIM capabilities compared to IFC2X3. 
 
 .. tip::
 
@@ -57,10 +59,10 @@ Navigating a model in 3D
 ------------------------
 
 To navigate, can use the **Navigate Gizmo** on the top right corner of the
-**Viewport** panel. Click and drag on the coloured axes to **Orbit**, click and
-drag on the magnifying glass to **Zoom**, and click and drag on the hand icon to
-**Pan**.  You can also click on the grid icon to switch between perspective and
-orthographic view.
+:menuselection:`3D Viewport`. Click and drag on the coloured axes to **Orbit**,
+click and drag on the magnifying glass to **Zoom**, and click and drag on the
+hand icon to **Pan**.  You can also click on the grid icon to switch between
+perspective and orthographic view.
 
 To switch to a top view, front view, or side view, click the relevant axis on
 the **Navigate Gizmo**.
@@ -68,42 +70,44 @@ the **Navigate Gizmo**.
 .. image:: images/navigate-gizmo.png
 
 You can also use your mouse to navigate. Hover your mouse over the **Viewport**
-panel and click and drag the Middle Mouse Button (``MMB``) to **Orbit**. Scroll
-the mousewheel to **Zoom**, and use ``Shift-MMB`` to **Pan**.
+panel and click and drag the Middle Mouse Button (:kbd:`MMB`) to **Orbit**.
+Scroll the mousewheel to **Zoom**, and use :kbd:`Shift-MMB` to **Pan**.
 
 If you have a numpad, you can use the numpad keys to quickly switch to top,
-front, or side view. Use ``7`` for top view, ``1`` for front view, and ``3`` for
-side view.
+front, or side view. Use :kbd:`7` for top view, :kbd:`1` for front view, and
+:kbd:`3` for side view.
 
 .. warning::
 
    Blender's hotkeys are context sensitive. This means that a hotkey has a
    different meaning depending on the panel your mouse cursor is hovering over.
-   If you press ``7`` to go to top view, make sure your mouse cursor is over the
-   **Viewport** panel. Be very careful where your mouse is, or you might press a
-   hotkey and it will have unintended consequences!
+   If you press :kbd:`7` to go to top view, make sure your mouse cursor is over the
+   :menuselection:`3D Viewport`. Be very careful where your mouse is, or you
+   might press a hotkey and it will have unintended consequences!
 
-If you click on an object, such as a wall in the **Viewport** panel, you can
-zoom to the selected object by clicking on ``View > Frame Selected``. The hotkey
-is the ``.`` button on the numpad. After zooming into an element, when you
-**Orbit** the 3D view will rotate around the center of that element.
+If you click on an object, such as a wall in the :menuselection:`3D Viewport`,
+you can zoom to the selected object by clicking on :menuselection:`3D Viewport
+--> View` then **Frame Selected**. The hotkey is the :kbd:`.` button on the
+numpad.  After zooming into an element, when you **Orbit** the 3D view will
+rotate around the center of that element.
 
-You can also zoom to all objects in the project by clicking on ``View > Frame
-All``.
+You can also zoom to all objects in the project by clicking on
+:menuselection:`3D Viewport --> View` then **Frame All**.
 
 .. image:: images/frame-selected.png
 
 Another good way to navigate is by flying or walking around similar to a video
-game. Choose ``View > Navigation > Walk Navigation``, or use the ``Shift-```
-hotkey (the backtick key is usually to the left of the number 1 on the
-keyboard). With **Walk Navigation** enabled, use the ``WASD`` keys and the mouse
-to move around like a video game. You can use the ``Shift`` key to switch
-between moving fast and slow. If you scroll with the mousewheel, it will adjust
-the speed that you move at.
+game. Click on :menuselection:`3D Viewport --> Explore Tool`, then you can
+press :kbd:`Shift-W` to activate **Walk Mode**. Use the :kbd:`WASD` keys and
+the mouse to move around like a video game. You can use the :kbd:`Shift` key to
+switch between moving fast and slow. If you scroll with the mousewheel, it will
+adjust the speed that you move at.
+
+.. image:: images/explore-tool.png
 
 Sometimes, you want to look through objects. You can toggle **X-Ray Mode** by
 pressing the button on the top right of the **Viewport** panel. The hotkey is
-``Alt-Z``.
+:kbd:`Alt-Z`.
 
 .. image:: images/x-ray-mode.png
 

src/bonsai/docs/reference/properties.rst

@@ -3,58 +3,29 @@ Properties
 
 .. container:: location-scene
 
-   |location| Scene Properties
+   |location| Properties
 
    .. |location| image:: /images/location-scene.svg
 
-Bonsai adds new functionality to the `Property Editor` -> `Scene` tab.
+The properties panel shows information about the IFC model and the actively
+selected IFC object in the 3D Viewport.
 
-.. figure:: images/interface_property-editor_project-overview_start-up.png
-   :alt: Property editor on Blender start-up
+Tab bar
+-------
 
-   The property editor on Blender startup.
+A horizontal row of icons are provided to switch between what type of
+properties are shown. Alternatively, a dropdown list may also be used.
 
-Most of these sub-tabs become available with a created or loaded IFC file.
-Don't worry, the default Blender scene properties are still reachable under their own dedicated sub-tab.
+.. image:: images/properties-tabs.png
 
-.. figure:: images/interface_property-editor_icons.png
-   :alt: Overview over the added property sub-tabs by Bonsai
-
-   Overview over the added property sub-tabs by Bonsai.
-
-1. Project Overview
-2. Object Information
-3. Geometry and Materials
-4. Drawings and Documents
-5. Services and Systems
-6. Structural Analyses
-7. Costing and Scheduling
-8. Facility Management
-9. Quality and Coordination
-10. Blender Properties
-11. Switch Tab
-
-You can also select the needed panel via the drop-down menue.
-
-.. figure:: images/interface_property-editor_panel-dropdown.png
-   :alt: Bonsai property editor sub-tabs drop-down menue
-
-   Switching between Bonsai property editor sub-tabs via the drop-down menue.
-
-
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-   :caption: Contents:
-
-   project_overview/index
-   object_information/index
-   geometry_and_materials/index
-   drawings_and_documents/index
-   services_and_systems/index
-   structural_analysis/index
-   costing_and_scheduling/index
-   facility_management/index
-   quality_and_coordination/index
-   blender
-   switch_tab
+- **Project Overview**: Overall project information.
+- **Object Information**: Simple properties and relationships about the actively selected object.
+- **Geometry and Materials**: Geometric, material, and style data.
+- **Drawings and Documents**: Drawings, sheets, schedules, and other documents.
+- **Services and Systems**: Mechanical, electrical, hydraulic, fire systems, and building physics.
+- **Structural Analysis**: Structural analytical models and analysis.
+- **Costing and Scheduling**: Project staging, quantity take-off, cost schedules, work schedules and animation, and resource management.
+- **Facility Management**: Facility management integration, Brickschema integration.
+- **Quality and Coordination**: Model auditing and fixing, clash detection, BCF collaboration, and debugging.
+- **Blender Properties**: (Only visible at the bottom of the dropdown menu) Shows default Blender panels for Blender users who do not want to see IFC information.
+- **Switch Tab** (:kbd:`Ctrl` + :kbd:`Tab`): (Only visible at the end of the tab icons) Toggles between the two last active tabs.

src/bonsai/docs/reference/topbar.rst

@@ -1,44 +1,100 @@
 Topbar
 ======
 
-For general informations about the Blender Topbar see the respective 
-`Workspaces <https://docs.blender.org/manual/en/latest/interface/window_system/topbar.html>`__ section in Blender documentation.
+.. container:: location-scene
 
-Menus
------
+   |location| Topbar
 
-The `File` menu in the Topbar adds menu entries to Create/Open and Save an IFC project directly.
+   .. |location| image:: /images/location-scene.svg
 
-.. figure:: images/interface_window_file-menue.png
-   :alt: Additional file menu options related to IFC projects
-   
-   Additional file menu options related to IFC projects.
+.. seealso::
+
+    See more documentation about the `Blender Topbar <https://docs.blender.org/manual/en/latest/interface/window_system/topbar.html>`__.
+
+File
+----
+
+.. container:: location-scene
+
+   |location| Topbar |>| File
+
+   .. |location| image:: /images/location-scene.svg
+   .. |>| image:: /images/location-breadcrumb.svg
+
+Access new, open, save, and import functionality.
+
+.. image:: images/topbar-file.png
+
+- :ref:`reference/topbar:new ifc project` (:kbd:`Ctrl` + :kbd:`N`): Provides convenient presets to create new IFC projects.
+- **Open IFC Project**: Launches a file browser to open an IFC model for viewing and authoring.
+- :ref:`reference/topbar:open recent ifc project`: See recently opened IFC models.
+- **Save IFC Project** (:kbd:`Shift` + :kbd:`S`): saves the ``.ifc`` file, optionally launching a file browse dialog if the file has not yet been saved.
+- **Save IFC Project As**: launches a file browse dialog to save the ``.ifc``. This location is remembered for future saves.
+- **Revert IFC Project**: Discards all unsaved changes and reloads the currently loaded IFC model.
+- :ref:`reference/topbar:import`: Imports data from external sources into the Blender session or IFC model.
+
+.. warning::
+
+    Other menu items, such as ``New`` or ``Open...`` are part of Blender. These
+    create, open, save, and interact with Blender files, not IFC models. If you
+    are using Bonsai to work with IFC natively, using these functions may
+    damage your IFC model. For more information, see
+    :ref:`guides/troubleshooting:saving and loading blend files`.
 
 New IFC Project
-^^^^^^^^^^^^^^^
+---------------
 
-The New IFC Project submenu offers several options for creating a new IFC project:
+.. container:: location-scene
 
-.. figure:: images/file_new-ifc-project-submenu.png
-   :alt: New IFC Project submenu options
-   
-   New IFC Project submenu options
+   |location| Topbar |>| File |>| New IFC Project (:kbd:`Shift` + :kbd:`N`)
 
-- New Metric (m) Project: Creates a new IFC project using meters as the base unit.
-- New Metric (mm) Project: Creates a new IFC project using millimeters as the base unit.
-- New Imperial (ft) Project: Creates a new IFC project using feet as the base unit.
-- New Demo Project: Creates a new IFC project with pre-populated demo content.
-- New Project Wizard: Creates a default Blender project (including the default cube)
-  and opens the Scene Properties > Project Overview > Project Info tab.
-  This allows users to customize their project settings before creation.
-  Clicking the "Create Project" button in this panel will delete the default cube and set up the new IFC project with the specified settings.
+   .. |location| image:: /images/location-scene.svg
+   .. |>| image:: /images/location-breadcrumb.svg
 
-These options provide flexibility in setting up new IFC projects,
-allowing users to choose between quick starts with predefined units
-or a more customizable approach through the Project Wizard.
+Provides convenient presets to create new IFC projects.
 
+.. image:: images/topbar-file-new.png
 
-BIM Workspace
--------------
+- **New Metric (m) Project**: Creates a new IFC4 project using meters as the length unit.
+- **New Metric (mm) Project**: Creates a new IFC4 project using millimeters as the length unit.
+- **New Imperial (ft) Project**: Creates a new IFC4 project using feet as the length unit.
+- **New Demo Project**: Creates a new IFC4 project with pre-populated demo types and content. Useful for experimenting and learning.
+- **New Project Wizard**: Resets the Blender session and shows the :ref:`viewing/project_overview:new project wizard` panel to customise project creation settings such as schema version.
 
-Bonsai adds the **BIM** Workspace to the Topbar Workspaces tabs.
+Open Recent IFC Project
+-----------------------
+
+.. container:: location-scene
+
+   |location| Topbar |>| File |>| Open Recent IFC Project
+
+   .. |location| image:: /images/location-scene.svg
+   .. |>| image:: /images/location-breadcrumb.svg
+
+Shows a list of recently opened IFC models.
+
+- **Clear Recent IFC Projects List**: Clears the list of recently opened IFC models.
+
+.. image:: images/topbar-file-recent.png
+
+Import
+------
+
+.. container:: location-scene
+
+   |location| Topbar |>| File |>| Import
+
+   .. |location| image:: /images/location-scene.svg
+   .. |>| image:: /images/location-breadcrumb.svg
+
+Imports data from external sources into the Blender session or IFC model.
+
+.. image:: images/topbar-file-import.png
+
+- **IFC (Geometry Only) (.ifc/.ifczip/.ifcxml)**: Imports only the geometry from an IFC model into the current Blender session. This can not be used for editing the IFC model. Typically used by CG artists.
+- **Cost Schedule (.csv)**: Imports a CSV containing a cost schedule into the active IFC model.
+- **Work Schedule (.csv)**: Imports a CSV containing a work schedule into the active IFC model.
+- **P6 (.xml)**: Imports a P6 XML file containing a work schedule into the active IFC model.
+- **P6 (.xer)**: Imports a P6 XER file containing a work schedule into the active IFC model.
+- **Powerproject (.pp)**: Imports a Powerproject file containing a work schedule into the active IFC model.
+- **Microsoft Project (.xml)**: Imports a Microsoft Project XML file containing a work schedule into the active IFC model.

src/bonsai/docs/reference/workspace.rst

@@ -1,26 +0,0 @@
-Workspace
-=========
-
-For general informations about the Blender Workspaces see the respective 
-`Workspaces <https://docs.blender.org/manual/en/latest/interface/window_system/workspaces.html>`__ section in Blender documentation.
-
-After installation of Bonsai the default Blender start-up screen looks different from the standard Blender interface.
-
-Bonsai adds the **BIM** Workspace to the interface and by default activates this workspace on start-up.
-It also modifies the layout of views and sidebars and adds custom functionality to the toolbar.
-The left **Outliner** panel shows a tree of geometric objects. The centre main **Viewport** panel shows 3D geometry.
-The right **Properties** panel shows data and relationships.
-
-.. figure:: images/interface_window_start-up.png
-   :alt: Blender start-up window with installed Bonsai
-
-   Blender start-up window with installed Bonsai.
-
-1. **BIM** Workspace tab
-2. Outliner with the document tree
-3. Main 3D viewport
-4. Property editor
-5. Toolbar with added BIM functionality
-6. Sidebar with Bonsai & 4D/5D Toolkit panels
-7. Status bar with information about the currently used Blender and Bonsai version
-