Update docs with Visual Studio Code instructions

docs/getting-started.md

@@ -6,8 +6,15 @@ SignalFlow supports macOS, Linux (including Raspberry Pi), and has alpha support
 
 ## Installation
 
- - [Installing SignalFlow on macOS](installation/macos.md)
- - [Installing SignalFlow on Linux](installation/linux.md)
+### macOS
+
+If you are an existing Python user and confident with the command line:
+
+[macOS: Install SignalFlow from the command line](installation/macos/command-line.md){ .md-button }
+
+If you're new to Python or getting started from scratch: 
+
+[macOS: Install SignalFlow with Visual Studio Code](installation/macos/easy.md){ .md-button } 
 
 ## Examples
 

docs/installation/macos/command-line.md

@@ -0,0 +1,37 @@
+# SignalFlow: Command-line installation for macOS
+
+These instructions assume you have a working version of Python 3.8+, installed either via [Homebrew](http://brew.sh) or from [Python.org](https://www.python.org/downloads/).
+
+## 1. Set up a virtual environment
+
+We strongly recommend setting up a dedicated Python "virtual environment" for SignalFlow
+
+```
+python3 -m venv signalflow-env
+source signalflow-env/bin/activate
+```
+
+## 2. Install SignalFlow
+
+Installing SignalFlow with `pip`:
+
+```shell
+pip3 install signalflow jupyter
+python3 -m ipykernel install --name signalflow-env
+```
+
+If the installation succeeds, you should see `Successfully installed signalflow`.
+
+## 3. Line test
+
+The installation of SignalFlow includes a command-line tool, `signalflow`, that can be used to test and configure the framework. Check that the installation has succeeded by playing a test tone through your default system audio output.
+
+This may take a few seconds to run for the first time. To exit the test, press ctrl-C (`^C`).
+
+```
+signalflow test
+```
+
+## Examples
+
+[Several example scripts](https://github.com/ideoforms/signalflow/tree/master/examples/python) are included within the repo, covering simple control and modulation, FM synthesis, sample granulation, MIDI control, chaotic functions, etc.

docs/installation/macos/easy.md

@@ -0,0 +1,89 @@
+# SignalFlow: Easy install for macOS
+
+The simplest way to start exploring SignalFlow is with the free [Visual Studio Code](https://code.visualstudio.com/) editor. Visual Studio Code can edit interactive "Jupyter" notebooks, which allow you to run and modify blocks of Python code in real-time, which is a great way to experiment live with audio synthesis.
+
+## 1. Install Python
+
+Download and install the latest version of Python (currently 3.12).
+
+[Download Python](https://www.python.org/downloads/){ .md-button }
+
+## 2. Download and install Visual Studio Code
+
+Download and install the latest version of Visual Studio Code.
+
+[Download Visual Studio Code](https://code.visualstudio.com/Download){ .md-button }
+
+## 3. Create a new Visual Studio Code workspace
+
+Open Visual Studio Code, select `File → Open Folder...`, select `New Folder`, and create a new folder that will contain all your new SignalFlow project.
+
+## 4. Install the Python and Jupyter extensions
+
+Visual Studio Code requires some extensions to be installed to handle Python and Jupyter files.
+
+In Visual Studio Code, select the `Extensions` icon from in the far-left column (or press `⇧⌘X`), and install the `Python` and `Jupyter` extensions by searching their names. These are needed to modify Jupyter notebooks in real-time.
+
+Once installation has finished, close the `Extensions` tab.
+
+## 5. Create a notebook in Visual Studio Code
+
+Select `File → New File...` (`^⌥⌘N`), and select `Jupyter Notebook`. You should see the screen layout change to display an empty black text block (in Jupyter parlance, a "cell"). 
+
+## 6. Create a Python virtual environment to use
+
+Click the button marked `Select Kernel` in the top right. 
+
+ - Select `Python Environments...`
+ - Select `Create Python Environment`
+ - Select `Venv`
+ - Finally, select the version of Python you just installed (`3.12.x`).
+
+Visual Studio Code will launch into some activity, in which it is installing necessary libraries and creating a Python "virtual environment", which is an isolated area of the filesystem containing all of the packages needed for this working space. Working in different virtual environments for different projects is good practice to minimise the likelihood of conflicts and disruptions.
+
+When the setup is complete, the button in the top right should change to say `.venv (Python 3.12.x)`.
+
+You're now all set to start writing code!
+
+## 7. Start writing code
+
+In the first block, type:
+
+```python
+print("Hello, world")
+```
+
+To run the cell, press `^↵` (control-enter). You should see "Hello, world" appear below the cell. You're now able to edit, change and run Python code in real-time!
+
+!!! info "Keyboard shortcuts"
+    - Navigate between cells with the arrow keys
+    - Use `enter` to begin editing a cell, and `escape` to end editing and move to select mode
+    - In select mode, use `b` to add a cell after the current cell, and `a` to add a cell before it 
+    - To evaluate a cell and move on to the next cell, use `⇧↵` (shift-enter)
+
+## 8. Start a SignalFlow session
+
+Clear the first cell, and replace it with:
+
+```python
+from signalflow import *
+```
+
+Run the cell with `^↵`. This imports all of the SignalFlow commands and classes.
+
+Create a new cell (`b`), and in the new cell, run:
+
+```python
+graph = AudioGraph()
+```
+
+This will create and start a new global audio processing system, using the system's default audio output. You should see the name of the audio device printed to the notebook.
+
+In a new cell, run:
+
+```python
+sine = SineOscillator(440) * 0.1
+sine.play()
+```
+
+This will create a sine oscillator, attenuate it, and play it from the system. Hopefully you should now hear a tone playing from your speaker or headphones.

mkdocs.yml

@@ -18,15 +18,19 @@ extra:
 
 markdown_extensions:
  - admonition
+ - attr_list
  - pymdownx.tabbed
  - pymdownx.highlight
  - pymdownx.superfences
 
 nav:
  - Home:
    - Home: index.md
+   - Getting started: getting-started.md
    - Installation:
-     - Installing on macOS: installation/macos.md
+     - Installing on macOS:
+        - Easy install: installation/macos/easy.md
+        - Command-line installation: installation/macos/command-line.md
      - Installing on Linux: installation/linux.md
      - Working with SignalFlow: installation/working.md
    - Examples: examples.md