From 9736d08064edd6414c165f5233f104a61c8cc571 Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Thu, 21 Sep 2023 13:21:13 +1000 Subject: [PATCH] Migrate more documentation to the official Sphinx docs and mention IfcOpenShell-WASM as an installation option --- src/bcf/README.md | 85 +------------------ src/bsdd/README.md | 20 +---- .../docs/bimserver-plugin.rst | 15 +--- src/ifcopenshell-python/docs/bimtester.rst | 14 +-- src/ifcopenshell-python/docs/bsdd.rst | 56 ++++++++++++ src/ifcopenshell-python/docs/conf.py | 1 + src/ifcopenshell-python/docs/ifccobie.rst | 16 ---- src/ifcopenshell-python/docs/ifcfm.rst | 4 + src/ifcopenshell-python/docs/ifcmax.rst | 20 +++++ .../docs/ifcopenshell-python/installation.rst | 18 +++- src/ifcopenshell-python/docs/index.rst | 5 +- 11 files changed, 107 insertions(+), 147 deletions(-) create mode 100644 src/ifcopenshell-python/docs/bsdd.rst delete mode 100644 src/ifcopenshell-python/docs/ifccobie.rst create mode 100644 src/ifcopenshell-python/docs/ifcfm.rst create mode 100644 src/ifcopenshell-python/docs/ifcmax.rst diff --git a/src/bcf/README.md b/src/bcf/README.md index a792c4f79f..aa1e4951e3 100644 --- a/src/bcf/README.md +++ b/src/bcf/README.md @@ -1,84 +1,5 @@ # bcf -A simple Python implementation of BCF. -Manipulation of BCF-XML is available via `bcfxml.py` and manipulation of BCF-API -is available via `bcfapi.py`. - -It tries to support BCF-XML version 2.1 and 3.0, and BCF-API 3.0. - -## bcfxml - -The `bcfxml.load` function lets you read a BCF-XML file. -It takes care of using the right version based on the "bcf.version" file contained in the BCF package. - -The BCF files are extracted and parsed on-demand, and edits are stored in memory until you call the `save` method. - -```python -from bcf.bcfxml import load - -# Load a project -with load("/path/to/file.bcf") as bcfxml: - project = bcfxml.project - print(project.name) - - # To edit a project, just modify the object directly - bcfxml.project.name = "New name" - - # Get a dictionary of topics - topics = bcfxml.topics - - for topic_guid, topic_handler in bcfxml.topics.items(): - topic = topic_handler.topic - print("Topic guid is", topic.guid) - print("Topic title is", topic.title) - - # Fetch extra data about a topic - header = topic_handler.header - comments = topic_handler.comments - viewpoints = topic_handler.viewpoints - - for comment in comments: - print(comment.guid) - print(comment.comment) - print(comment.author) - - # Get a particular topic - topic = bcfxml.get_topic(guid) - - # Modify a topic - topic.title = "New title" - - bcfxml.save() -``` - -## bcfapi - -The `bcfapi` module lets you interact with the BCF-API standard. - -```python -from bcf.v3.bcfapi import FoundationClient, BcfClient - -foundation_client = FoundationClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET", "OPENCDE_BASEURL") -auth_methods = foundation_client.get_auth_methods() - -# Our library currently only implements the authorization_code flow -if "authorization_code" in auth_methods: - foundation_client.login() - -bcf_client = BcfClient(foundation_client) - -versions = foundation_client.get_versions() -for version in versions: -if "3.0" in versions: - if version["api_id"] == "bcf" and version["version_id"] == "3.0": - bcf_client.set_version(version) - -data = bcf_client.get_projects() -print(data) -project_id = data[0]["project_id"] -print(project_id) -data = bcf_client.get_project(project_id) -print(data) -data = bcf_client.get_extensions(project_id) -print(data) -``` +A simple Python implementation of the BCF standard. Manipulation of BCF-XML is +available via `bcfxml.py` and manipulation of BCF-API is available via +`bcfapi.py`. diff --git a/src/bsdd/README.md b/src/bsdd/README.md index 215845a321..5d92dbe9d5 100644 --- a/src/bsdd/README.md +++ b/src/bsdd/README.md @@ -1,21 +1,3 @@ # bsdd -An experimental work in progress library to interact with the buildingSMART Data Dictionary (bSDD) API. - -More reading: - - * [Swagger API docs](https://bs-dd-api-prototype.azurewebsites.net/swagger/index.html) - * [bSDD Github Repository](https://github.com/buildingSMART/bSDD) - -# Demo - -Let's replicate the SketchUp example: - -``` -client = Client() -pprint(client.Domain()) -pprint(client.SearchListOpen("http://identifier.buildingsmart.org/uri/nlsfb/nlsfb2005-2.2", RelatedIfcEntity="IfcWall")) -data = client.Classification("http://identifier.buildingsmart.org/uri/nlsfb/nlsfb2005-2.2/class/21.21") -pprint(data) -apply_ifc_classification_properties(ifc_file, element, data["classificationProperties"]) -``` +A library to interact with the buildingSMART Data Dictionary (bSDD) API. diff --git a/src/ifcopenshell-python/docs/bimserver-plugin.rst b/src/ifcopenshell-python/docs/bimserver-plugin.rst index 432c499f87..b9d9beae07 100644 --- a/src/ifcopenshell-python/docs/bimserver-plugin.rst +++ b/src/ifcopenshell-python/docs/bimserver-plugin.rst @@ -1,16 +1,5 @@ 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` +The BIMServer-Plugin is a plugin to the open source BIMServer CDE to allow you +to use IfcOpenShell to parse, view, and audit models. diff --git a/src/ifcopenshell-python/docs/bimtester.rst b/src/ifcopenshell-python/docs/bimtester.rst index 8640df8bab..bdecbc2131 100644 --- a/src/ifcopenshell-python/docs/bimtester.rst +++ b/src/ifcopenshell-python/docs/bimtester.rst @@ -1,16 +1,4 @@ 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` +BIMTester is a utility that allows you to write Gherkin-based tests for models. diff --git a/src/ifcopenshell-python/docs/bsdd.rst b/src/ifcopenshell-python/docs/bsdd.rst new file mode 100644 index 0000000000..d8f53b4f0f --- /dev/null +++ b/src/ifcopenshell-python/docs/bsdd.rst @@ -0,0 +1,56 @@ +bSDD +==== + +The **buildingSMART Data Dictionary** (bSDD) is an online RESTful centralised +API provided by buildingSMART that allows you to search for standardised +classifications and properties. + +For example, if you want to assign a Uniclass classification system (popular in +the UK) or an Omniclass classification system (popular in the US) to elements +in your model, instead of downloading the classification system from their +website, you can directly search the bSDD. This ensures that you are always up +to date, and that codes are entered correctly (without spelling mistakes, +correct formatting, etc). + +The bSDD search results may also be filtered based on IFC class. This will make +it quick to shortlist relevant classification codes and properties to a +particular object. + +The bSDD also stores information on whether or not classification systems +require additional standard properties to be filled out, and whether they +should be filled out in a particular way. For example, all countries need to +fill out a "Fire Rating" property for walls, but they have different ways to +fill it out. Local governments (or companies) may submit their standard to the +bSDD so that all bSDD-compatible BIM applications can look up the property and +fill it out in a standardised way (such as picking for a list of preset +possible values defined by the local government). + +More reading: + +1. `Swagger API docs `_ +2. `bSDD Github Repository `_ + +Examples +-------- + +Learning how to use the bSDD is best done by reading the official Swagger API docs. + +.. code-block:: python + + client = Client() + + # Get a list of "dictionary domains". For example, Uniclass (by the NBS organisation) might be one domain. + print(client.Domain()) + + # For example, search the Netherland's Nlsfb2005 classification standard for all codes that apply to an IfcWall. + print(client.SearchListOpen("http://identifier.buildingsmart.org/uri/nlsfb/nlsfb2005-2.2", RelatedIfcEntity="IfcWall")) + + # Alternatively, search up a particular classification code. + data = client.Classification("http://identifier.buildingsmart.org/uri/nlsfb/nlsfb2005-2.2/class/21.21") + print(data) + + # You may also apply default properties (if the classification system on + # the bSDD defines them) to your IFC element. For example, if a + # classification code is for a load bearing wall, it can automatically set + # the "LoadBearing" property to True for you. + apply_ifc_classification_properties(ifc_file, element, data["classificationProperties"]) diff --git a/src/ifcopenshell-python/docs/conf.py b/src/ifcopenshell-python/docs/conf.py index b766df476c..4bc3f18fd8 100644 --- a/src/ifcopenshell-python/docs/conf.py +++ b/src/ifcopenshell-python/docs/conf.py @@ -67,6 +67,7 @@ autoapi_type = 'python' # autoapi works by reading source code instead of importing modules autoapi_dirs = ['../ifcopenshell', '../../ifcdiff', '../../ifcpatch/ifcpatch'] +autoapi_dirs = ['../../ifcdiff', '../../ifcpatch/ifcpatch'] # These are auto-generated based on the IFC schema, so exclude them autoapi_ignore = ['*ifcopenshell/express/rules*'] diff --git a/src/ifcopenshell-python/docs/ifccobie.rst b/src/ifcopenshell-python/docs/ifccobie.rst deleted file mode 100644 index 35ba047267..0000000000 --- a/src/ifcopenshell-python/docs/ifccobie.rst +++ /dev/null @@ -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` diff --git a/src/ifcopenshell-python/docs/ifcfm.rst b/src/ifcopenshell-python/docs/ifcfm.rst new file mode 100644 index 0000000000..cefbe99a87 --- /dev/null +++ b/src/ifcopenshell-python/docs/ifcfm.rst @@ -0,0 +1,4 @@ +IfcFM +===== + +IfcFM is a utility to diff --git a/src/ifcopenshell-python/docs/ifcmax.rst b/src/ifcopenshell-python/docs/ifcmax.rst new file mode 100644 index 0000000000..a564e15b93 --- /dev/null +++ b/src/ifcopenshell-python/docs/ifcmax.rst @@ -0,0 +1,20 @@ +IfcMax +====== + +IfcMax is a 3ds Max importer plugin able to import the IFC file format. + +Community builds are available for 3ds Max by Josef Wienerroither (also known +as ``FrogsInSpace`` or ``spacefrog``). Builds are available for IfcOpenShell +v0.7.0 for 3ds Max version 2020-2024. Older builds are also available for +IfcOpenShell v0.6.0 for 3ds Max version 2015-2022. + +It is recommended to use the latest version of IfcOpenShell and 3ds Max. + +- `Visit FrogsInSpace official website for IfcMax `__. +- `Download IfcMax plugins `__. + +.. note:: + + This plugin is purely an importer and does not handle native IFC authoring + or exporting. For more information for native IFC authoring, we recommend + using the :doc:`BlenderBIM Add-on`. diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst index 5c0d1b045a..8dc7811f1d 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst @@ -11,9 +11,10 @@ packages**. If you aren't a programmer, go for the **BlenderBIM Add-on**. 4. **Docker** is recommended for developers using Docker. 5. **AWS Lambda** is recommended for developers using AWS Lambda functions. 6. **Google Colab** is recommended for developers using Google Colab. -7. **Using the BlenderBIM Add-on** is recommended for non-developers wanting a graphical interface. -8. **From source with precompiled binaries** is recommended for developers actively working with the Python code. -9. **Compiling from source** is recommended for developers actively working with the C++ core. +7. **Web Assembly** is recommended for developers experimenting with IfcOpenShell on the web. +8. **Using the BlenderBIM Add-on** is recommended for non-developers wanting a graphical interface. +9. **From source with precompiled binaries** is recommended for developers actively working with the Python code. +10. **Compiling from source** is recommended for developers actively working with the C++ core. Pre-built packages ------------------ @@ -197,6 +198,17 @@ local system. `__ to launch a simple notebook. +Web Assembly +------------ + +IfcOpenShell is available as technology preview to be run using WASM. This +allows you to run IfcOpenShell in a browser using pyodide. This implementation +is incredibly heavy and will incur a long load time, but once loaded, will give +you full access to the entire IfcOpenShell API. + +`Click here `__ to learn how to +use WASM. + Using the BlenderBIM Add-on --------------------------- diff --git a/src/ifcopenshell-python/docs/index.rst b/src/ifcopenshell-python/docs/index.rst index f5bd6086d0..4aca839ad3 100644 --- a/src/ifcopenshell-python/docs/index.rst +++ b/src/ifcopenshell-python/docs/index.rst @@ -22,16 +22,19 @@ IfcOpenShell is a suite of developer libraries and utilities to manipulate OpenB :maxdepth: 1 :caption: Utilities: + bcf bimserver-plugin bimtester + bsdd ifc2ca ifc4d ifc5d ifccityjson ifcclash - ifccobie ifccsv ifcdiff + ifcfm + ifcmax ifcpatch ifcsverchok ifctester