doc update

.github/workflows/release.yaml

@@ -32,7 +32,6 @@ jobs:
       contents: write
     needs: build
     steps:
-      # We need to be in a git repo for gh to work.
       - uses: actions/checkout@v4
 
       - uses: actions/download-artifact@v4

README.md

@@ -1,17 +1,22 @@
+[![CI](https://github.com/ikappaki/basilisp-blender/actions/workflows/tests-run.yml/badge.svg)](https://github.com/ikappaki/basilisp-blender/actions/workflows/tests-run.yml)
+
 # Basilisp Blender Integration
+
+[Basilisp](https://github.com/basilisp-lang/basilisp) is a Python-based Lisp implementation that offers broad compatibility with Clojure.
+
 ## Overview
-`basilisp_blender` is a Python library designed to facilitate the execution of Basilisp code within Blender and manage an nREPL server for interactive programming. This library provides functions to evaluate Basilisp code from Blender's Python console, file or Text Editor and to start an nREPL server, allowing seamless integration and communication with Basilisp.
+`basilisp-blender` is a Python library designed to facilitate the execution of Basilisp code within Blender and manage an nREPL server for interactive programming. This library provides functions to evaluate Basilisp code from Blender's Python console, file or Text Editor and to start an nREPL server, allowing seamless integration and communication with Basilisp.
 
 ## Features
 * Evaluate Basilisp Code: Execute Basilisp code snippets directly from code strings, files or Blender’s text editor.
 * Start an nREPL Server: Launch an nREPL server within Blender, supporting interactive development and debugging.
 
 ## Installation
-To install `basilisp_blender`, use `pip` from Blender's Python console:
+To install `basilisp-blender`, use `pip` from Blender's Python console:
 
 ```python
 import pip
-pip.main(['install', 'basilisp_blender'])
+pip.main(['install', 'basilisp-blender'])
 ```
 
 ## Usage
@@ -53,5 +58,82 @@ To start an nREPL server within Blender:
 from basilisp_blender.nrepl import server_start
 
 ```python
-shtudown_fn = server_start(port=8889)
+shtudown_fn = server_start(host="127.0.0.1", port=8889)
 ```
+
+The `host` and `port` arguments are optional. If not provided, the server will bind to a random local port. It will also creates an `.nrepl-port` file in the current working directory containing the port number it bound to.
+
+The return value is a function that you can call without arguments to shut down the server.
+
+For a more convinient setup, you can specify the path to a `.nrepl-port` file in your Basilisp's project's root directory. This allows some Clojure editors (such as CIDER or Calva) to automatically detect the port and connect to the server:
+
+```python
+shtudown_fn = server_start(nrepl_port_filepath="<project-root-path>/.nrepl-port")
+```
+
+Replace `<project-root-path>` with the path to your project's root directory.
+
+#Example
+
+Basilisp code to create a torus pattern using the `bpy` Blender library:
+
+```clojure
+(ns torus-pattern
+  "Creates a torus pattern with random colored materials."
+  (:import bpy
+           math))
+
+(def object (-> bpy/ops .-object))
+(def materials (-> bpy/data .-materials))
+(def mesh (-> bpy/ops .-mesh))
+
+
+(defn clear-mesh-objects []
+  (.select-all object ** :action "DESELECT")
+  (.select-by-type object ** :type "MESH")
+  (.delete object))
+
+(clear-mesh-objects)
+
+(defn create-random-material []
+  (let [mat (.new materials ** :name "RandomMaterial")
+        _ (set! (.-use-nodes mat) true)
+        bsdf (aget (-> mat .-node-tree .-nodes) "Principled BSDF")]
+
+    (set! (-> bsdf .-inputs (aget "Base Color") .-default-value)
+          [(rand) (rand) (rand) 1])
+    mat))
+
+(defn create-torus [radius tube-radius location segments]
+  (let [_ (.primitive-torus-add mesh **
+                                :major-radius radius
+                                :minor-radius tube-radius
+                                :location location
+                                :major-segments segments
+                                :minor-segments segments)
+        obj (-> bpy/context .-object)
+        material (create-random-material)]
+    (-> obj .-data .-materials (.append material))))
+
+#_(create-torus 5, 5, [0 0 0] 48)
+
+(defn create-pattern [{:keys [layers-num radius tube-radius]
+                       :or {layers-num 2
+                            radius 2
+                            tube-radius 0.2}}]
+  (let [angle-step (/ math/pi 4)]
+    (dotimes [i layers-num]
+      (let [layer-radius (* radius (inc i))
+            objects-num (* 12 (inc i))]
+        (dotimes [j objects-num]
+          (let [angle (* j angle-step)
+                x (* layer-radius (math/cos angle))
+                y (* layer-radius (math/sin angle))
+                z (* i 0.5)]
+            (create-torus (/ radius 2) tube-radius [x y z] 48)))))))
+
+(create-pattern {:layers-num 5})
+```
+
+![torus pattern example img](examples/torus-pattern.png)
+

examples/torus_pattern.lpy

@@ -0,0 +1,55 @@
+(ns torus-pattern
+  "Creates a torus pattern with random colored materials."
+  (:import bpy
+           math))
+
+(def object (-> bpy/ops .-object))
+(def materials (-> bpy/data .-materials))
+(def mesh (-> bpy/ops .-mesh))
+
+
+(defn clear-mesh-objects []
+  (.select-all object ** :action "DESELECT")
+  (.select-by-type object ** :type "MESH")
+  (.delete object))
+
+(clear-mesh-objects)
+
+(defn create-random-material []
+  (let [mat (.new materials ** :name "RandomMaterial")
+        _ (set! (.-use-nodes mat) true)
+        bsdf (aget (-> mat .-node-tree .-nodes) "Principled BSDF")]
+
+    (set! (-> bsdf .-inputs (aget "Base Color") .-default-value)
+          [(rand) (rand) (rand) 1])
+    mat))
+
+(defn create-torus [radius tube-radius location segments]
+  (let [_ (.primitive-torus-add mesh **
+                                :major-radius radius
+                                :minor-radius tube-radius
+                                :location location
+                                :major-segments segments
+                                :minor-segments segments)
+        obj (-> bpy/context .-object)
+        material (create-random-material)]
+    (-> obj .-data .-materials (.append material))))
+
+#_(create-torus 5, 5, [0 0 0] 48)
+
+(defn create-pattern [{:keys [layers-num radius tube-radius]
+                       :or {layers-num 2
+                            radius 2
+                            tube-radius 0.2}}]
+  (let [angle-step (/ math/pi 4)]
+    (dotimes [i layers-num]
+      (let [layer-radius (* radius (inc i))
+            objects-num (* 12 (inc i))]
+        (dotimes [j objects-num]
+          (let [angle (* j angle-step)
+                x (* layer-radius (math/cos angle))
+                y (* layer-radius (math/sin angle))
+                z (* i 0.5)]
+            (create-torus (/ radius 2) tube-radius [x y z] 48)))))))
+
+(create-pattern {:layers-num 5})

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "basilisp-blender"
-version = "0.0.0b25"
+version = "0.0.0b28"
 description = ""
 authors = ["ikappaki"]
 readme = "README.md"

src/basilisp_blender/nrepl.py

@@ -1,6 +1,7 @@
 """Functions that depend on the `bpy` module."""
 
 import atexit
+import sys
 from pathlib import Path
 
 from basilisp_blender.eval import eval_str
@@ -33,6 +34,7 @@ def server_thread_async_start(host="127.0.0.1", port=0, nrepl_port_filepath=None
       [work-fn shutdown-fn])
 """
     )
+    assert work_fn and shutdown_fn, ":server-error :could-not-be-started"
 
     return work_fn, shutdown_fn
 

src/basilisp_blender/nrepl_server.lpy

@@ -529,7 +529,8 @@
                                                     (clients-work-do! work* notify-fn)))
                                         :shutdown-fn (partial server-shutdown! server)}))
          (let [[host port] (py->lisp (.-server-address server))]
-           (println (format nrepl-server-signature port host host port))
+           (binding [*out* sys/stdout]
+             (println (format nrepl-server-signature port host host port)))
            (spit nrepl-port-file (str port)))
          (when start-event (.set start-event))
          (.serve-forever server)