Update installation docs

docs/index.md

@@ -56,5 +56,5 @@ In subsequent examples, we will skip the `import` line and assume you have alrea
 
 ## Documentation
 
-- [Installation](installation)
+- [Installation](installation/index)
 - [Example code](http://github.com/ideoforms/signalflow/tree/master/examples/python)

docs/installation/macos.md

@@ -0,0 +1,58 @@
+# Installing SignalFlow on macOS
+
+Installing SignalFlow requires some basic terminal usage. Open Terminal via Finder in `Applications > Utilities > Terminal`.
+
+## 1. Install Python
+
+Download and install the latest version of Python (3.12) from [Python.org](https://www.python.org/downloads/).
+
+To check that it has worked, run the below command in Terminal and confirm that it prints a version starting with 3.12:
+
+```
+python3 --version
+```
+
+## 2. Set up a virtual environment
+
+To ensure that your SignalFlow Python install does not conflict with other Python packages on your system, we strongly recommend setting up a dedicated Python "virtual environment" for SignalFlow, which is a self-contained area of the file system containing all of the Python packages and binaries needed for the system.
+
+To create the virtual environment:
+
+```
+python3 -m venv signalflow-env
+```
+
+!!! info
+    You can replace `signalflow-env` with whatever name you would like to call the virtual environment.
+    You can also create this virtual env anywhere on your drive, by changing the directory with `cd some/other/path`.
+
+To activate the virtual environment:
+
+```
+source signalflow-env/bin/activate
+```
+
+## 3. Install SignalFlow
+
+Installing SignalFlow is done using the `pip` Python package manager. The below line will install the `signalflow` library, plus support for `jupyter` interactive Python notebooks, and register your virtual environment system-wide so that notebooks can access it.
+
+```
+pip3 install signalflow jupyter
+python3 -m ipykernel install --name signalflow-env
+```
+
+That's it!
+
+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:
+
+```
+signalflow test
+```
+
+## 4. Work with SignalFlow
+
+Now, let's set up an editor to [work with SignalFlow](/installation/working/). 
+
+## 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/working.md

@@ -0,0 +1,58 @@
+# Work with SignalFlow
+
+The recommended way to start exploring SignalFlow is by using the free [Visual Studio Code](https://code.visualstudio.com/) as an 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. Download and install Visual Studio Code
+
+Visual Studio Code is a [free download from visualstudio.com](https://code.visualstudio.com/Download).
+
+### 2. Install the Python and Jupyter extensions
+
+In Visual Studio Code, browse to `Extensions` via the far-left icons (or press `⇧⌘X`), and install the `Python` and `Jupyter` extensions. These are needed to modify Jupyter notebooks in real-time.
+
+### 3. Create a notebook in Visual Studio Code
+
+Create a new text file in Visual Studio Code (`⌘N`), and save it to a new file with an `.ipynb` extension. This tells VS Code that you are creating a Python notebook. You should see the screen layout change to display an empty black text block (in Jupyter parlance, a "cell").
+
+### 4. 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)
+
+### 5. 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

@@ -23,7 +23,10 @@ markdown_extensions:
 nav:
  - Home:
    - Home: index.md
-   - Installation: installation.md
+   - Installation:
+     - Installing on macOS: installation/macos.md
+     - Installing on Linux: installation/linux.md
+     - Working with SignalFlow: installation/working.md
    - Examples: examples.md
    - License: license.md
  - The AudioGraph: