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

.gitignore

@@ -67,3 +67,6 @@ htmlcov
 
 # Blender
 *.blend1
+
+# Sphinx
+_build/

src/blenderbim/docs/_static/custom.css

@@ -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;
+}

src/blenderbim/docs/conf.py

@@ -35,12 +35,12 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "IfcOpenShell"
+project = "BlenderBIM Add-on"
-copyright = "2020, IfcOpenShell Contributors"
+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"]

src/blenderbim/docs/devs/hello_world.rst

@@ -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

src/blenderbim/docs/devs/installation.rst

@@ -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.
+1. **Unstable installation** is recommended for power users helping with testing.
-2. **Unstable installation** is recommended for power users helping with testing.
+2. **Building from source** is recommended for distributing a build from source.
-3. **Building from source** is recommended for distributing a build from source.
+3. **Live development environment** is recommended for developers who are actively coding.
-4. **Live development environment** is recommended for developers who are actively coding.
+4. **Distro installation** is recommended for those who use a Linux package manager.
-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.
 
 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.

src/blenderbim/docs/index.rst

@@ -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
+   users/installation
-   ifcopenshell-python
+   users/exploring_an_ifc_model
-   ifcconvert
+   users/creating_your_first_ifc
-   blenderbim
-   bimtester
-   ifcdiff
-   ifcclash
-   ifccobie
-   ifcmax
-   ifcsverchok
-   bimserver-plugin
 
+.. toctree::
+   :hidden:
+   :maxdepth: 1
+   :caption: For developers:
 
-Indices and tables
+   devs/installation
-==================
+   devs/hello_world
-
+   devs/running_tests
-* :ref:`genindex`
+   devs/undo_system
-* :ref:`modindex`
+   devs/ux_guidelines
-* :ref:`search`
+   devs/georeferencing

src/blenderbim/docs/users/installation.rst

@@ -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.

src/ifcopenshell-python/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

src/ifcopenshell-python/docs/conf.py

@@ -0,0 +1,72 @@
+# BlenderBIM Add-on - OpenBIM Blender Add-on
+# Copyright (C) 2020, 2021 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of BlenderBIM Add-on.
+#
+# BlenderBIM Add-on is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# BlenderBIM Add-on is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with BlenderBIM Add-on.  If not, see <http://www.gnu.org/licenses/>.
+
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "IfcOpenShell"
+copyright = "2020, IfcOpenShell Contributors"
+author = "IfcOpenShell Contributors"
+
+# The full version, including alpha/beta/rc tags
+release = "0.0.1"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx.ext.autodoc"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+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"]

src/ifcopenshell-python/docs/index.rst

@@ -0,0 +1,32 @@
+Let's learn IfcOpenShell
+========================
+
+IfcOpenShell is a 
+
+A coloured icon: :octicon:`report;1em;sd-text-info`, some more text.
+
+:bdg:`plain badge`
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   ifcopenshell
+   ifcopenshell-python
+   ifcconvert
+   blenderbim
+   bimtester
+   ifcdiff
+   ifcclash
+   ifccobie
+   ifcmax
+   ifcsverchok
+   bimserver-plugin
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

src/ifcopenshell-python/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd