From 8cff046a46bccb080981814fd94447616422661f Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Tue, 11 Jun 2024 17:32:30 +1000 Subject: [PATCH] Doc download links now point to explicitly versioned releases, not bot builds This ensures that IOS-Python always 1) has the appropriate version and 2) contains exactly the same content as PyPI (i.e. with the latest Python files that might be outdated from the bot builds) --- .github/workflows/ci-ifcopenshell-docker.yml | 1 - src/blenderbim/Makefile | 1 - src/ifcopenshell-python/docs/conf.py | 26 ++++-- .../docs/ifcopenshell-python/installation.rst | 80 ++++++------------- 4 files changed, 43 insertions(+), 65 deletions(-) diff --git a/.github/workflows/ci-ifcopenshell-docker.yml b/.github/workflows/ci-ifcopenshell-docker.yml index 9b150c2588..ab2a1d0245 100644 --- a/.github/workflows/ci-ifcopenshell-docker.yml +++ b/.github/workflows/ci-ifcopenshell-docker.yml @@ -6,7 +6,6 @@ on: tags: - v0.** - jobs: activate: diff --git a/src/blenderbim/Makefile b/src/blenderbim/Makefile index 6a025599b6..0d4fd0f67c 100644 --- a/src/blenderbim/Makefile +++ b/src/blenderbim/Makefile @@ -87,7 +87,6 @@ bump: cd . && $(SED) "s/$(OLD)/$(NEW)/" Makefile cd ../ifcopenshell-python/ && $(SED) "s/$(OLD)/$(NEW)/" Makefile cd ../ifcopenshell-python/docs/ifcconvert/ && $(SED) "s/$(OLD)/$(NEW)/" installation.rst - cd ../ifcopenshell-python/docs/ifcopenshell-python/ && $(SED) "s/$(OLD)/$(NEW)/" installation.rst .PHONY: dist dist: diff --git a/src/ifcopenshell-python/docs/conf.py b/src/ifcopenshell-python/docs/conf.py index 083292ff96..64fbdfa8d8 100644 --- a/src/ifcopenshell-python/docs/conf.py +++ b/src/ifcopenshell-python/docs/conf.py @@ -30,7 +30,8 @@ # import os import sys -sys.path.insert(0, os.path.abspath('..')) + +sys.path.insert(0, os.path.abspath("..")) # -- Project information ----------------------------------------------------- @@ -44,6 +45,18 @@ cwd = os.path.dirname(os.path.realpath(__file__)) with open(os.path.join(cwd, "..", "..", "..", "VERSION"), "r") as f: release = f.read().strip() +from docutils import nodes + + +def versioned_link_role(name, rawtext, text, lineno, inliner, options={}, content=[]): + url = f"https://github.com/IfcOpenShell/IfcOpenShell/releases/download/ifcopenshell-python-{release}/ifcopenshell-python-{release}-{text}.zip" + node = nodes.reference(rawtext, text, refuri=url, **options) + return [node], [] + + +def setup(app): + app.add_role("ios_python_url", versioned_link_role) + # -- General configuration --------------------------------------------------- @@ -65,7 +78,7 @@ autosectionlabel_prefix_document = True autoapi_add_toctree_entry = True # We're only documenting Python here -autoapi_type = 'python' +autoapi_type = "python" # autoapi works by reading source code instead of importing modules autoapi_dirs = ['../ifcopenshell', '../../bcf/src', '../../bsdd', '../../ifccsv', '../../ifcdiff', '../../ifcpatch/ifcpatch', '../../ifctester/ifctester'] @@ -86,10 +99,10 @@ autoapi_template_dir = "_autoapi_templates" # ifcopenshell.file is imported from ifcopenshell.file.file, but it gets pretty # confusing to see the docs again in multiple places (seriously, # ifcopenshell.file.file is everywhere). -autoapi_options = ['members', 'undoc-members', 'show-inheritance', 'imported-members'] +autoapi_options = ["members", "undoc-members", "show-inheritance", "imported-members"] # This option is set to both to allow both class docstrings and __init__ docstrings. -autoapi_python_class_content = 'both' +autoapi_python_class_content = "both" # Group by type (e.g. attribute, class, function, etc) then alphabetically. autoapi_member_order = "groupwise" @@ -139,7 +152,7 @@ html_theme_options = { "color-link--visited": "#39b54a", "color-link--hover": "#d98014", "color-link--visited--hover": "#d98014", - "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji" + "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji", }, "dark_css_variables": { "color-brand-primary": "#39b54a", @@ -153,9 +166,8 @@ html_theme_options = { "color-link--visited": "#39b54a", "color-link--hover": "#d98014", "color-link--visited--hover": "#d98014", - "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji" + "font-stack": "Nunito, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif, Apple Color Emoji, Segoe UI Emoji", }, - "footer_icons": [ { "name": "IfcOpenShell", diff --git a/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst b/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst index ddca648e24..bf26e0eda7 100644 --- a/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst +++ b/src/ifcopenshell-python/docs/ifcopenshell-python/installation.rst @@ -2,11 +2,12 @@ Installation ============ There are different methods of installation, depending on your situation. If -you aren't sure which to choose, if you're a programmer, go for the **Pre-built -packages**. If you aren't a programmer, go for the **BlenderBIM Add-on**. +you aren't sure which to choose, if you're a programmer, go for **PyPI** if you +use Pip, otherwise go for the **ZIP packages**. If you aren't a programmer, go +for the **BlenderBIM Add-on**. -1. **Pre-built packages** is recommended for users wanting to use the latest IfcOpenShell builds. -2. **PyPI** is recommended for developers using Pip. +1. **PyPI** is recommended for developers using Pip. +2. **ZIP packages** is recommended for users doing a manual installation. 3. **Conda** is recommended for developers using Anaconda. 4. **Docker** is recommended for developers using Docker. 5. **AWS Lambda** is recommended for developers using AWS Lambda functions. @@ -16,49 +17,30 @@ packages**. If you aren't a programmer, go for the **BlenderBIM Add-on**. 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 ------------------- +PyPI +---- -Pre-built packages are prepared sporadically depending on whether there are -changes in the IfcOpenShell C++ core. This will give you the latest available -C++ bindings, but may potentially contain outdated pure Python modules, such as -the API. +.. code-block:: + + pip install ifcopenshell + +ZIP packages +------------ 1. Choose which version to download based on your operating system, Python version, and computer architecture. - +-------------+----------------+----------------+----------------+-------------------+---------------------+ - | | Linux 64bit | Windows 32bit | Windows 64bit | MacOS Intel 64bit | MacOS Silicon 64bit | - +=============+================+================+================+===================+=====================+ - | Python 3.9 | py39-linux64_ | py39-win32_ | py39-win64_ | py39-macos64_ | py39-macosm164_ | - +-------------+----------------+----------------+----------------+-------------------+---------------------+ - | Python 3.10 | py310-linux64_ | py310-win32_ | py310-win64_ | py310-macos64_ | py310-macosm164_ | - +-------------+----------------+----------------+----------------+-------------------+---------------------+ - | Python 3.11 | py311-linux64_ | py311-win32_ | py311-win64_ | py311-macos64_ | py311-macosm164_ | - +-------------+----------------+----------------+----------------+-------------------+---------------------+ - | Python 3.12 | py312-linux64_ | py312-win32_ | py312-win64_ | py312-macos64_ | py312-macosm164_ | - +-------------+----------------+----------------+----------------+-------------------+---------------------+ - -.. _py39-linux64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-39-v0.8.0-90ae709-linux64.zip -.. _py310-linux64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-310-v0.8.0-90ae709-linux64.zip -.. _py311-linux64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-311-v0.8.0-90ae709-linux64.zip -.. _py312-linux64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-312-v0.8.0-90ae709-linux64.zip -.. _py39-win32: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-39-v0.8.0-90ae709-win32.zip -.. _py310-win32: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-310-v0.8.0-90ae709-win32.zip -.. _py311-win32: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-311-v0.8.0-90ae709-win32.zip -.. _py312-win32: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-312-v0.8.0-90ae709-win32.zip -.. _py39-win64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-39-v0.8.0-90ae709-win64.zip -.. _py310-win64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-310-v0.8.0-90ae709-win64.zip -.. _py311-win64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-311-v0.8.0-90ae709-win64.zip -.. _py312-win64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-312-v0.8.0-90ae709-win64.zip -.. _py39-macos64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-39-v0.8.0-90ae709-macos64.zip -.. _py310-macos64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-310-v0.8.0-90ae709-macos64.zip -.. _py311-macos64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-311-v0.8.0-90ae709-macos64.zip -.. _py312-macos64: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-312-v0.8.0-90ae709-macos64.zip -.. _py39-macosm164: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-39-v0.8.0-90ae709-macosm164.zip -.. _py310-macosm164: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-310-v0.8.0-90ae709-macosm164.zip -.. _py311-macosm164: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-311-v0.8.0-90ae709-macosm164.zip -.. _py312-macosm164: https://s3.amazonaws.com/ifcopenshell-builds/ifcopenshell-python-312-v0.8.0-90ae709-macosm164.zip + +-------------+---------------------------------+-------------------------------+-------------------------------+---------------------------------+-----------------------------------+ + | | Linux 64bit | Windows 32bit | Windows 64bit | MacOS Intel 64bit | MacOS Silicon 64bit | + +=============+=================================+===============================+===============================+=================================+===================================+ + | Python 3.9 | :ios_python_url:`py39-linux64` | :ios_python_url:`py39-win32` | :ios_python_url:`py39-win64` | :ios_python_url:`py39-macos64` | :ios_python_url:`py39-macosm164` | + +-------------+---------------------------------+-------------------------------+-------------------------------+---------------------------------+-----------------------------------+ + | Python 3.10 | :ios_python_url:`py310-linux64` | :ios_python_url:`py310-win32` | :ios_python_url:`py310-win64` | :ios_python_url:`py310-macos64` | :ios_python_url:`py310-macosm164` | + +-------------+---------------------------------+-------------------------------+-------------------------------+---------------------------------+-----------------------------------+ + | Python 3.11 | :ios_python_url:`py311-linux64` | :ios_python_url:`py311-win32` | :ios_python_url:`py311-win64` | :ios_python_url:`py311-macos64` | :ios_python_url:`py311-macosm164` | + +-------------+---------------------------------+-------------------------------+-------------------------------+---------------------------------+-----------------------------------+ + | Python 3.12 | :ios_python_url:`py312-linux64` | :ios_python_url:`py312-win32` | :ios_python_url:`py312-win64` | :ios_python_url:`py312-macos64` | :ios_python_url:`py312-macosm164` | + +-------------+---------------------------------+-------------------------------+-------------------------------+---------------------------------+-----------------------------------+ 2. Unzip the downloaded file and copy the ``ifcopenshell`` directory into your Python path. If you're not sure where your Python path is, run the following @@ -81,20 +63,6 @@ the API. print(ifcopenshell.version) model = ifcopenshell.file() -PyPI ----- - -PyPI releases are automatically performed once a month and contain the latest -Python code that point in time. - -Releases on PyPI may potentially ship slightly outdated precompiled binaries of -the C++ core. This is because the binaries typically go through a period of -manual testing prior in case of high-risk changes. - -.. code-block:: - - pip install ifcopenshell - Conda -----