Split BlenderBIM and other docs to not overwhelm users. Use Furo theme for Sphinx.

2026-09-16 21:42:19 +00:00 · 2022-05-04 13:06:39 +10:00
parent 6e55a04550
commit 8c3e29c351
38 changed files with 334 additions and 108 deletions
@@ -0,0 +1,10 @@
+.blockbutton {
+    border: 1px solid var(--color-admonition-title--seealso);
+    background-color: var(--color-admonition-title-background--seealso);
+    padding: 5px;
+    text-align: center;
+    border-radius: 5px;
+    max-width: 500px;
+    margin-left: auto;
+    margin-right: auto;
+}
@@ -1,16 +0,0 @@
-BIMServer-Plugin
-================
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,16 +0,0 @@
-BIMTester
-=========
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -35,12 +35,12 @@

 # -- Project information -----------------------------------------------------

-project = "IfcOpenShell"
-copyright = "2020, IfcOpenShell Contributors"
+project = "BlenderBIM Add-on"
+copyright = "2020-2022 IfcOpenShell Contributors"
 author = "IfcOpenShell Contributors"

 # The full version, including alpha/beta/rc tags
-release = "0.0.1"
+release = "0.0.220504"


 # -- General configuration ---------------------------------------------------
@@ -64,9 +64,11 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = "nature"
+html_theme = "furo"

 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ["_static"]
+
+html_css_files = ["custom.css"]
@@ -1,5 +1,5 @@
-Developer guide
-===============
+Hello, world!
+=============

 The BlenderBIM Add-on takes a unique approach to authoring BIM data. Traditional
 BIM authoring apps create features that are tailored for a single discipline's
@@ -1,28 +1,12 @@
-.. _blenderbim/installation:
-
 Installation
 ============

 There are different methods of installation, depending on your situation.

-1. **Stable installation** is recommended for regular users.
-2. **Unstable installation** is recommended for power users helping with testing.
-3. **Building from source** is recommended for distributing a build from source.
-4. **Live development environment** is recommended for developers who are actively coding.
-5. **Distro installation** is recommended for those who use a Linux package manager.
-
-Stable installation
-------------------
-
-The BlenderBIM Add-on is packaged like a regular Blender add-on, so installation
-is the same as any other Blender add-on. The full instructions for end-user
-installation is available at the `Get BlenderBIM
-<https://blenderbim.org/download.html>`__ website. The latest release is
-typically updated every few weeks.
-
-Like all Blender add-ons, they can be installed using ``Edit > Preferences >
-Addons > Install > Choose Downloaded ZIP > Enable Add-on Checkbox``. You can
-enable add-ons permanently by using ``Save User Settings`` from the Addons menu.
+1. **Unstable installation** is recommended for power users helping with testing.
+2. **Building from source** is recommended for distributing a build from source.
+3. **Live development environment** is recommended for developers who are actively coding.
+4. **Distro installation** is recommended for those who use a Linux package manager.

 Unstable installation
 ---------------------
@@ -226,65 +210,3 @@ Required static assets are:

    bim/data/gantt/jsgantt.js (from jsgantt-improved)
    bim/data/gantt/jsgantt.css (from jsgantt-improved)
-
-Where is the BlenderBIM Add-on installed?
-----------------------------------------
-
-If you downloaded Blender as a ``.zip`` file without running an installer, you
-will find the BlenderBIM Add-on installed in the following directory, where
-``X.XX`` is the Blender version:
-::
-
-    /path/to/blender/X.XX/scripts/addons/
-
-Otherwise, if you installed Blender using an installation package, the add-ons
-folder depends on which operating system you use. On Linux:
-::
-
-    ~/.config/blender/X.XX/scripts/addons/
-
-On Mac:
-::
-
-    /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/
-
-On Windows:
-::
-
-    C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\scripts\addons
-
-Upon installation, the BlenderBIM Add-on is stored in the ``blenderbim/``
-directory.
-
-Updating
--------
-
-First uninstall the current BlenderBIM add-on, then install the latest version.
-
-Uninstalling
------------
-
-Navigate to ``Edit > Preferences > Add-ons``. Due to a limitation in Blender,
-you have to first disable the BlenderBIM Add-on in your Blender preferences by
-pressing the checkbox next to the add-on, then restart Blender. After
-restarting, you can uninstall the BlenderBIM Add-on by pressing the ``Remove``
-button in the Blender preferences window.
-
-Alternatively, you may uninstall manually by deleting the ``blenderbim/``
-directory in your Blender add-ons directory.
-
-FAQ
---
-
-1. I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.7'"
-
-Check which BlenderBIM Add-on build you are using. The zip will have either
-``py37``, ``py39``, or ``py310`` in the name. See the instructions in the
-**Unstable installation** section to check that you have installed the correct
-version.
-
-2. 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.
@@ -1,16 +0,0 @@
-IfcClash
-========
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,16 +0,0 @@
-IfcCOBie
-========
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,16 +0,0 @@
-IfcConvert
-==========
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,16 +0,0 @@
-IfcDiff
-=======
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,16 +0,0 @@
-IfcMax
-======
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,19 +0,0 @@
-IfcOpenShell-Python
-===================
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-   ifcopenshell-python/quickstart
-   ifcopenshell-python/api-documentation
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,21 +0,0 @@
-API Documentation
-=================
-
-.. automodule:: ifcopenshell.entity_instance
-   :members:
-
-.. automodule:: ifcopenshell.file
-   :members:
-
-.. automodule:: ifcopenshell.guid
-   :members:
-
-
-.. automodule:: ifcopenshell.template
-   :members:
-
-.. automodule:: ifcopenshell.validate
-   :members:
-
-.. automodule:: ifcopenshell.ids
-   :members:
@@ -1,5 +0,0 @@
-Quickstart
-==========
-
-For starters, you can read `Using IfcOpenShell to parse IFC files with Python
-<https://thinkmoult.com/using-ifcopenshell-parse-ifc-files-python.html>`_
@@ -1,16 +0,0 @@
-IfcOpenShell
-============
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,18 +0,0 @@
-IfcSverchok
-===========
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-   ifcsverchok/installation
-
-Indices and tables
------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
@@ -1,109 +0,0 @@
-Installation
-============
-
-There are different methods of installation, depending on your situation.
-
-1. **Packaged installation** is recommended for regular users.
-2. **Daily build installation** is recommended for power users helping with testing.
-3. **Source installation** is recommended for developers.
-
-Packaged installation
---------------------
-
-IfcSverchok is packaged like a regular Blender add-on, so installation is the
-same as any other Blender add-on. You can download the package for installation
-at the `Get BlenderBIM <https://blenderbim.org/download.html>`__ website.
-
-Like all Blender add-ons, they can be installed using ``Edit > Preferences >
-Addons > Install > Choose Downloaded ZIP > Enable Add-on Checkbox``. You can
-enable add-ons permanently by using ``Save User Settings`` from the Addons menu.
-
-Before installing, you will also need to `install the BlenderBIM Add-on
-<../blenderbim/installation>`__ and `install Sverchok
-<https://github.com/nortikin/sverchok#installation>`__.
-
-If you downloaded Blender as a ``.zip`` file without running an installer, you
-will find IfcSverchok installed in the following directory, where ``2.XX`` is
-the Blender version:
-::
-
-    /path/to/blender/2.XX/scripts/addons/
-
-Otherwise, if you installed Blender using an installation package, the add-ons
-folder depends on which operating system you use. On Linux:
-::
-
-    ~/.config/blender/2.XX/scripts/addons/
-
-On Mac:
-::
-
-    /Users/{YOUR_USER}/Library/Application Support/Blender/2.XX/
-
-On Windows:
-::
-
-    C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\2.XX\scripts\addons
-
-Upon installation, IfcSverchok is stored in the ``ifcsverchok/`` directory.
-
-Daily build installation
------------------------
-
-Daily builds are almost the same as **Packaged installation**, except that they
-are typically updated every day. Simply download a daily build from the `Github
-releases page <https://github.com/IfcOpenShell/IfcOpenShell/releases>`__, then
-follow the same instructions as a packaged installation.
-
-TODO: daily builds not yet available
-
-Daily builds are not always stable. Sometimes, a build may be delayed, or
-contain broken code. We try to avoid this, but it happens.
-
-Source installation
-------------------
-
-It is possible to run the latest bleeding edge version of IfcSverchok without
-having to wait for an official release, since IfcSverchok is coded in Python and
-doesn't require any compilation.
-
-Just symbolically link the IfcSverchok add-on files to your Git repository. If
-you're on Windows, use ``mklink`` instead. This allows us to code in our Git
-repository, and see the changes in our Blender installation.
-
-::
-
-    $ git clone https://github.com/IfcOpenShell/IfcOpenShell.git
-    $ cd IfcOpenShell
-
-    # Link the repository to blender
-    $ ln -s src/ifcsverchok /path/to/blender/2.XX/scripts/addons/ifcsverchok
-    
-On Windows:
-
-::
-
-    $ git clone https://github.com/IfcOpenShell/IfcOpenShell.git
-    $ cd IfcOpenShell
-
-    # Link the repository to blender
-    $ mklink /D "\path\to\blender\2.XX\scripts\addons\ifcsverchok" "\path\to\src\ifcsverchok"
-
-After you modify your code in the Git repository, you will need to restart
-Blender for the changes to take effect. In ``Edit > Preferences > Add-ons`` you
-will see that the version number of IfcSverchok has changed to ``0.0.999999``,
-which represents an un-versioned IfcSverchok.
-
-Updating
--------
-
-First uninstall the current IfcSverchok, then install the latest version.
-
-Uninstalling
------------
-
-Navigate to ``Edit > Preferences > Add-ons``, find the IfcSverchok add-on, and
-press ``Remove``.
-
-Alternatively, you may uninstall manually by deleting the ``ifcsverchok/``
-directory in your Blender add-ons directory.
@@ -1,26 +1,25 @@
-IfcOpenShell Documentation
-==========================
+Let's get started
+=================
+
+The BlenderBIM Add-on lets you analyse, create, and modify OpenBIM with Blender. 

 .. toctree::
+   :hidden:
   :maxdepth: 1
-   :caption: Contents:
+   :caption: For users:

-   ifcopenshell
-   ifcopenshell-python
-   ifcconvert
-   blenderbim
-   bimtester
-   ifcdiff
-   ifcclash
-   ifccobie
-   ifcmax
-   ifcsverchok
-   bimserver-plugin
+   users/installation
+   users/exploring_an_ifc_model
+   users/creating_your_first_ifc

+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: For developers:

-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   devs/installation
+   devs/hello_world
+   devs/running_tests
+   devs/undo_system
+   devs/ux_guidelines
+   devs/georeferencing
@@ -0,0 +1,131 @@
+Installation
+============
+
+1. **Download and install Blender**
+
+   Blender is a free and open-source program for 3D authoring. It works on
+   Linux, Mac, and Windows. It is developed by the Blender community.
+
+.. container:: blockbutton
+
+    `Download Blender <https://www.blender.org/download/>`__
+
+.. note::
+
+    No administrator rights on Windows? Choose the "Portable .zip" option when
+    downloading from the Blender website.
+
+2. **Download the BlenderBIM Add-on**
+
+   The BlenderBIM Add-on extends Blender with OpenBIM related capabilities.
+
+.. container:: blockbutton
+
+   `Download BlenderBIM Add-on <https://blenderbim.org/download.html>`__
+
+3. **Install the BlenderBIM Add-on**
+
+   Open up Blender, and access the ``Edit > Preferences`` window.
+
+   .. image:: install-blenderbim-1.png
+
+   Select the **Add-ons** tab, and press **Install...** on the top right. Navigate
+   to the .zip you downloaded in Step 2, and press **Install Add-on**.
+
+   .. image:: install-blenderbim-2.png
+
+   .. caution::
+   
+      You do not need to unzip the add-on file. You should install it as a zipped file.
+
+   You should now see **Import-Export: BlenderBIM** available in your add-ons list. Enable the add-on by pressing the checkbox.
+
+   .. image:: install-blenderbim-3.png
+
+All done! If you check your Scene properties in the panel on the bottom right, you will see a panel to manage your **IFC Project**.
+
+.. image:: install-blenderbim-4.png
+
+You can enable add-ons permanently by using ``Save User Settings`` from the Addons menu.
+
+.. seealso::
+
+    If you are a poweruser, you may be interested in the **Unstable installation** to help with testing. :doc:`Read more <../devs/installation>`
+
+Where is the add-on installed?
+------------------------------
+
+If you downloaded Blender as a ``.zip`` file without running an installer, you
+will find the BlenderBIM Add-on installed in the following directory, where
+``X.XX`` is the Blender version:
+::
+
+    /path/to/blender/X.XX/scripts/addons/
+
+Otherwise, if you installed Blender using an installation package, the add-ons
+folder depends on which operating system you use. On Linux:
+::
+
+    ~/.config/blender/X.XX/scripts/addons/
+
+On Mac:
+::
+
+    /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/
+
+On Windows:
+::
+
+    C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\scripts\addons
+
+Upon installation, the BlenderBIM Add-on is stored in the ``blenderbim/``
+directory.
+
+
+Updating
+--------
+
+First uninstall the current BlenderBIM add-on, then install the latest version.
+
+Uninstalling
+------------
+
+Navigate to ``Edit > Preferences > Add-ons``. Due to a limitation in Blender,
+you have to first disable the BlenderBIM Add-on in your Blender preferences by
+pressing the checkbox next to the add-on, then restart Blender. After
+restarting, you can uninstall the BlenderBIM Add-on by pressing the ``Remove``
+button in the Blender preferences window.
+
+Alternatively, you may uninstall manually by deleting the ``blenderbim/``
+directory in your Blender add-ons directory.
+
+.. caution::
+
+    It is important to follow the sequence of disabling, restarting, then removing.
+    If you do not restart Blender, the add-on will fail to remove correctly, and you
+    will need to uninstall manually.
+
+
+FAQ
+---
+
+1. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.7'"**
+
+   Check which BlenderBIM Add-on build you are using. The zip will have either
+   ``py37``, ``py39``, or ``py310`` in the name. See the instructions in the
+   **Unstable installation** section to check that you have installed the
+   correct version.
+
+2. **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.
+
+3. **The add-on does not install on a Mac with an M1 arm chip**
+
+   The BlenderBIM Add-on uses the IfcOpenShell library, which is not yet
+   available for computers which use an ARM chip. You may
+   compile IfcOpenShell yourself to get this to work, but this may be too
+   difficult for most users. Please consider donating so that we can devote more
+   time to supporting all platforms.