Improve documentation and clarify preferences

Author: PalashChitnavis

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"

brian2wasm/device.py

@@ -29,22 +29,34 @@
     'devices.wasm_standalone',
     'Preferences for the WebAsm backend',
     emsdk_directory=BrianPreference(
-        docs='''Path to the emsdk directory, containing the emsdk binary.''',
-        default=''
+        default="",
+        docs="""
+            Absolute path to the *emsdk* installation. Leave empty to use the
+            EMSDK/CONDA_EMSDK_DIR environment variables or an already-activated
+            emsdk in your shell.
+            """,
     ),
     emsdk_version=BrianPreference(
-        docs='''Version of the emsdk to use, defaults to "latest"''',
-        default="latest"
+        default="latest",
+        docs="""
+            Version string passed to ``emsdk activate`` (e.g. ``"3.1.56"``).
+            Ignored when *emsdk_directory* is empty and the SDK is pre-activated.
+            """,
     ),
     emcc_compile_args=BrianPreference(
-        default=[
-            "-w"
-        ],
-        docs="Extra flags appended to every emcc compile command",
+        default=["-w"],
+        docs="""
+            Extra flags appended to every *emcc* **compile** command.
+            Example: ``["-O3", "-sASSERTIONS"]``.
+            """,
     ),
     emcc_link_args=BrianPreference(
         default=[],
-        docs="Extra flags passed at link time",
+        docs="""
+            Extra flags appended to the final *emcc* **link** command that produces
+            ``wasm_module.js`` / ``.wasm``.
+            Example: ``["-sEXPORT_ES6", "-sEXPORTED_RUNTIME_METHODS=['cwrap']"]``.
+            """,
     ),
 )
 
@@ -397,6 +409,43 @@ def run(self, directory, results_directory, with_output, run_args):
             self.timers['run_binary'] = time.time() - start_time
 
     def build(self, html_file=None, html_content=None, **kwds):
+        """
+                Build the project for the WASM backend.
+
+                Parameters
+                ----------
+                directory : str, optional
+                    Target folder for the generated project. If ``None`` a temporary
+                    directory is created.  Default: ``"output"``.
+                results_directory : str, optional
+                    Relative sub-folder used at runtime to store simulation results.
+                    Default: ``"results"``.
+                compile : bool, optional
+                    Compile the generated sources with *emcc*.  Default: ``True``.
+                run : bool, optional
+                    Execute the produced JavaScript/WASM bundle after a successful
+                    build (headless node-style run).  Default: ``True``.
+                debug : bool, optional
+                    Add debug symbols and ``-g -DDEBUG`` flags.  Default: ``False``.
+                clean : bool, optional
+                    Remove previously compiled objects before building.  Default:
+                    ``False``.
+                with_output : bool, optional
+                    Forward the program’s stdout/stderr when running.  Default:
+                    ``True``.
+                additional_source_files : list[str] | None
+                    Extra ``.cpp`` files to compile alongside the generated Brian code.
+                run_args : list[str] | None
+                    Additional command-line arguments passed to the executable HTML/
+                    JS harness when *run* is ``True``.
+                direct_call : bool, optional
+                    ``True`` when invoked by user code, ``False`` when invoked
+                    automatically because ``build_on_run=True``.
+                **kwds
+                    Reserved for future keyword arguments; passing unknown names
+                    raises ``TypeError``.
+                """
+
         self.build_options.update({'html_file': html_file,
                                    'html_content': html_content})