Add conceptual documentation and example workflows

README.md

@@ -1,3 +1,9 @@
 # Bonsai - Python Scripting
 
-Bonsai.Scripting.Python is a [Bonsai](https://bonsai-rx.org/) interface for the [Python](https://www.python.org/) programming language. It uses [Python.NET](https://pythonnet.github.io/pythonnet/) under the hood to provide a seamless integration between the CPython runtime and data streaming in a Bonsai workflow.
+Bonsai.Scripting.Python is a [Bonsai](https://bonsai-rx.org/) interface for the [Python](https://www.python.org/) programming language. It uses [Python.NET](https://pythonnet.github.io/pythonnet/) under the hood to provide a seamless integration between the CPython runtime and data streaming in a Bonsai workflow.
+
+You can use the Python Scripting package to run native Python scripts, import any module available to Python, and read or write to any variable in a named scope. The package is designed to work with any Python version from 3.7 onwards, and you can also use it in combination with [Python virtual environments](https://docs.python.org/3/tutorial/venv.html) to fully isolate your project dependencies.
+
+## Documentation
+
+Both conceptual and reference documentation can be found [here](https://bonsai-rx.org/python-scripting/).

docs/articles/modules.md

@@ -0,0 +1,24 @@
+# Dynamic Modules
+
+The Python Scripting package allows you to define dynamic modules at runtime. This is useful if you need to isolate specific scripts, or keep track of state variables evolving independently in different parts of the workflow.
+
+To create a new module, you can use the [CreateModule](xref:Bonsai.Scripting.Python.CreateModule) operator together with a [ResourceSubject](xref:Bonsai.Reactive.ResourceSubject):
+
+:::workflow
+![CreateModule](~/workflows/create-module.bonsai)
+:::
+
+> [!Warning]
+> Make sure to always pair the [CreateModule](xref:Bonsai.Scripting.Python.CreateModule) operator together with a [ResourceSubject](xref:Bonsai.Reactive.ResourceSubject) to ensure that your module is correctly destroyed when your workflow terminates.
+
+Once the module is declared, you can now pass it to any of your Python operators to make sure they run their code in the correct scope:
+
+:::workflow
+![ShareModule](~/workflows/share-module.bonsai)
+:::
+
+> [!Tip]
+> You can think of modules as "objects", as they encapsulate all their state variables inside a unique Python scope.
+
+> [!Warning]
+> If you do not provide a specific module for a Python scripting operator to run in, it will always run in the global Python main module.

docs/articles/overview.md

@@ -2,10 +2,65 @@
 uid: overview
 ---
 
-Bonsai.Scripting.Python is a [Bonsai](https://bonsai-rx.org/) interface for the [Python](https://www.python.org/) programming language. It uses [Python.NET](https://pythonnet.github.io/pythonnet/) under the hood to provide a seamless integration between the CPython runtime and data streaming in a Bonsai workflow.
+The Python Scripting package is a [Bonsai](https://bonsai-rx.org/) interface for the [Python](https://www.python.org/) programming language. It uses [Python.NET](https://pythonnet.github.io/pythonnet/) under the hood to provide a seamless integration between the CPython runtime and data streaming in a Bonsai workflow.
 
-You can use Bonsai.Scripting.Python to run native Python scripts, import any module available to Python, and read or write to any variable in a named scope. The package is designed to work with any Python version from 3.7 onwards, and you can also use it in combination with [Python virtual environments](https://docs.python.org/3/tutorial/venv.html) to fully isolate your project dependencies.
+You can use the Python Scripting package to run native Python scripts, import any module available to Python, and read or write to any variable in a named scope. The package is designed to work with any Python version from 3.7 onwards, and you can also use it in combination with [Python virtual environments](https://docs.python.org/3/tutorial/venv.html) to fully isolate your project dependencies.
 
-## Installing the package
+## How to install
 
-To install Bonsai.Scripting.Python use the Bonsai package manager and search for the **Bonsai - Python Scripting** package.
+1. Download [Bonsai](https://bonsai-rx.org/).
+2. From the package manager, search and install the **Bonsai - Python Scripting** package.
+
+## Create a Python environment
+
+In addition to the Python Scripting package you need to have a version of [Python](https://www.python.org/) installed in your system. We recommend installing the official distributions and using `venv` to create virtual environments to run your specific projects.
+
+To create a virtual environment you can run the following command from inside the folder where you want to install the environment:
+
+```ps
+python -m venv example-env
+```
+
+## Create a Python runtime
+
+The [CreateRuntime](xref:Bonsai.Scripting.Python.CreateRuntime) node launches the Python kernel and creates the main global scope for running Python scripts. You must set the [PythonHome](xref:Bonsai.Scripting.Python.CreateRuntime.PythonHome) property to the environment folder (or your Python home directory) before starting the workflow:
+
+:::workflow
+![CreateRuntime](~/workflows/create-runtime.bonsai)
+:::
+
+Alternatively, you can activate the virtual environment *before* starting Bonsai. In this case you do not need to specify the Python home directory.
+
+> [!Tip]
+> You can set the value of the [**ScriptPath**](xref:Bonsai.Scripting.Python.CreateRuntime.ScriptPath) property to specify a main script that will be run when the Python runtime is initialized. This script can be used to import all the main modules to be used in your workflow, or initialize any state variables to be manipulated during execution.
+
+## Run Python code
+
+The [Eval](xref:Bonsai.Scripting.Python.Eval) operator can be used anywhere in your workflow to interact with the Python runtime, just as if you were writing code in the Python REPL:
+
+:::workflow
+![HelloPython](~/workflows/hello-python.bonsai)
+:::
+
+You can also use the [Exec](xref:Bonsai.Scripting.Python.Exec) operator to run Python statements dynamically, for example to import new modules:
+
+:::workflow
+![HelloPython](~/workflows/exec-eval.bonsai)
+:::
+
+## Read and write state variables
+
+To interface with Python state variables, you can use the [Get](xref:Bonsai.Scripting.Python.Get) and [Set](xref:Bonsai.Scripting.Python.Set) operators:
+
+:::workflow
+![GetSet](~/workflows/get-set.bonsai)
+:::
+
+> [!Warning]
+> All the operators in the Python Scripting package run under the Python [Global Interpreter Lock](https://docs.python.org/3/glossary.html#term-global-interpreter-lock). This means that although execution of Python code can be triggered asynchronously anywhere in the workflow, there will be a bottleneck when accessing the interpreter. Because of this, we currently do not recommend running large number of parallel calls to Python.
+
+## Scripting Extensions
+
+Custom script files can be executed when creating the Python runtime with [CreateRuntime](xref:Bonsai.Scripting.Python.CreateRuntime) or when creating a new module with [CreateModule](xref:Bonsai.Scripting.Python.CreateModule).
+
+To edit script files we recommend [Visual Studio Code](https://code.visualstudio.com/) and the [Python extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-python.python). If both your virtual environment and your custom Python scripts are placed relative to your main workflow, VS Code can be launched from the Bonsai IDE and will be able to correctly pick up the right environment when editing the scripts.

docs/articles/toc.yml

@@ -2,4 +2,6 @@
   href: intro.md
   items:
     - name: Quickstart
-      href: intro.md
+      href: intro.md
+    - name: Dynamic Modules
+      href: modules.md

docs/templates/html/styles/main.css

@@ -20,7 +20,8 @@
 
 .workflow {
   border: 1px solid #e3e3e3;
-  padding: 1px;
+  padding: 2px;
+  margin-bottom: 10px;
 }
 
 .workflow > p > img {

docs/workflows/create-module.bonsai

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<WorkflowBuilder Version="2.7.1"
+                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                 xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
+                 xmlns:rx="clr-namespace:Bonsai.Reactive;assembly=Bonsai.Core"
+                 xmlns="https://bonsai-rx.org/2018/workflow">
+  <Workflow>
+    <Nodes>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="py:CreateModule">
+          <py:Name>NewModule</py:Name>
+        </Combinator>
+      </Expression>
+      <Expression xsi:type="rx:ResourceSubject">
+        <Name>NewModule</Name>
+      </Expression>
+    </Nodes>
+    <Edges>
+      <Edge From="0" To="1" Label="Source1" />
+    </Edges>
+  </Workflow>
+</WorkflowBuilder>

docs/workflows/create-runtime.bonsai

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<WorkflowBuilder Version="2.7.1"
+                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                 xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
+                 xmlns="https://bonsai-rx.org/2018/workflow">
+  <Workflow>
+    <Nodes>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="py:CreateRuntime">
+          <py:PythonHome>example-env</py:PythonHome>
+        </Combinator>
+      </Expression>
+    </Nodes>
+    <Edges />
+  </Workflow>
+</WorkflowBuilder>

docs/workflows/exec-eval.bonsai

@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="utf-8"?>
+<WorkflowBuilder Version="2.7.1"
+                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                 xmlns:py="clr-namespace:Bonsai.Scripting.Python;assembly=Bonsai.Scripting.Python"
+                 xmlns="https://bonsai-rx.org/2018/workflow">
+  <Workflow>
+    <Nodes>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="py:CreateRuntime">
+          <py:PythonHome>example-env</py:PythonHome>
+        </Combinator>
+      </Expression>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="py:Exec">
+          <py:Script>from datetime import datetime</py:Script>
+        </Combinator>
+      </Expression>
+      <Expression xsi:type="Combinator">
+        <Combinator xsi:type="py:Eval">
+          <py:Expression>print(datetime.now())</py:Expression>
+        </Combinator>
+      </Expression>
+    </Nodes>
+    <Edges>
+      <Edge From="0" To="1" Label="Source1" />
+      <Edge From="1" To="2" Label="Source1" />
+    </Edges>
+  </Workflow>
+</WorkflowBuilder>