Refactor WASMStandaloneDevice Build: Drop distutils, add native emcc prefs

.github/workflows/test-pr.yml

@@ -17,11 +17,6 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      # Set up MSVC env (Windows)
-      - name: Set up MSVC env (Windows)
-        if: runner.os == 'Windows'
-        uses: ilammy/msvc-dev-cmd@v1
-
       # Install Pixi
       - name: Install pixi
         uses: prefix-dev/setup-pixi@v0.8.0

README.md

@@ -1,24 +1,52 @@
 # Brian2Wasm
 
-Wasm code generation for the [Brian simulator](https://briansimulator.org).
+**Brian2Wasm** is a [Brian 2](https://briansimulator.org/) “device” that compiles Brian models to WebAssembly and JavaScript via the [Emscripten](https://emscripten.org/) tool-chain.  
+The result is a self-contained web folder (`index.html`, `wasm_module.js`, and the `.wasm` binary) that runs your simulation in any modern browser.
 
-Using the [emscripten](https://emscripten.org/) toolchain, this "device" generates code in WebAssembly and JavaScript, enabling users to run Brian simulations in the browser.
+Live examples: <https://brian-team.github.io/brian2wasm/>
 
-You can directly access the built examples on this website: https://brian-team.github.io/brian2wasm/
+> **Status** – functional, but still under active development.
 
-**UNDER CONSTRUCTION, not for general use**
+[![PyPI](https://img.shields.io/pypi/v/brian2wasm.svg)](https://pypi.org/project/brian2wasm/)
 
-> [!WARNING]
-> The package currently only targets Linux – it might work on macOS and on Windows via the WSL, but this hasn't been tested.
+## Installation & Usage (Pixi)
 
-Usage/Installation:
-- Install `brian2wasm` with `pip`, either by cloning this repository and using `pip install .`, or by using
-  ```console
-  $ pip install git+https://github.com/brian-team/brian2wasm/
-  ```
-- Install the [emsdk](https://emscripten.org/docs/getting_started/downloads.html) and activate it following the instructions
-- You should then be able to run one of the examples in the [`examples` folder](/examples)
+```bash
+# 1 – install Pixi (https://pixi.sh)
+curl -fsSL https://pixi.sh/install.sh | bash
 
-> [!NOTE]
-> Plotting will not work in the website that gets started automatically by the example script, since it needs to download the `plotly.js` library from a CDN.
-> You can work around this limitation by going into the generated folder that contains the `index.html` file and run a Python webserver via `python -m http.server`. You can then open the displayed link in your browser.
+# 2 – set up Brian2Wasm
+git clone https://github.com/brian-team/brian2wasm.git
+cd brian2wasm
+pixi install          # creates the full env (Python, emsdk, brian2, …)
+pixi run setup        # one-time EMSDK activation
+pixi shell            # enter the environment shell
+
+# 3 – build and run an example
+python -m brian2wasm examples/brunel_hakim1999.py
+```
+
+## Headless build (no preview server)
+```bash
+python -m brian2wasm --no-server my_model.py
+```
+```--no-server``` skips the temporary web-server and only generates the files.
+
+
+> **⚠️ Limitations / Warnings**
+> * **Do not call `set_device(...)`** in your script—Brian2Wasm sets the device automatically.
+> * Plotly charts inside the generated HTML load assets from a CDN.
+
+
+## Contributing
+
+Contributions are welcome!  
+If you encounter a bug or have a feature request, please open an issue first.  
+Pull requests should target the `main` branch and follow conventional commit messages.
+
+---
+
+## License
+
+Brian2Wasm is released under the same open-source license as the core Brian 2 simulator (BSD-style).  
+See the `LICENSE` file in this repository for full details.

brian2wasm/__main__.py

@@ -3,6 +3,45 @@
 import os
 
 def main():
+    """
+        Command-line interface for **Brian2Wasm**.
+
+        Usage
+        -----
+        ``python -m brian2wasm <script.py> [--no-server]``
+
+        Parameters
+        ----------
+        script : str
+            Path to the user’s Python model. The file **must** end with
+            ``.py`` and must not call ``set_device`` itself – the CLI inserts
+            the appropriate ``set_device('wasm_standalone', …)`` line
+            automatically.
+        --no-server : flag, optional
+            Generate the WASM/HTML output without starting the local preview
+            web-server (sets the ``BRIAN2WASM_NO_SERVER`` environment
+            variable for the subprocess).
+
+        Behaviour
+        ---------
+        1. Validates that *script* exists and is a ``.py`` file.
+        2. Looks for an ``<scriptname>.html`` file in the same directory.
+           * If found, passes the HTML file to ``set_device`` so the custom
+             template is used.
+           * Otherwise falls back to the default template.
+        3. Prepends the required ``set_device('wasm_standalone', …)`` call to
+           the script source in-memory.
+        4. Executes the modified script with its own directory as working
+           directory, so any relative paths inside the model behave as
+           expected.
+
+        Exit status
+        -----------
+        * ``0`` – build finished successfully (and server started unless
+          *--no-server* was given).
+        * ``1`` – any error (missing file, not a ``.py`` file, exception
+          during model execution, etc.).
+        """
 
     parser = argparse.ArgumentParser(
         description="Brian2WASM CLI"