Update documentation style and navigation; add mkdocs includes

CONTRIBUTING.md

@@ -37,7 +37,7 @@ python3 setup.py test
 To generate and serve the docs:
 
 ```
-pip3 install mkdocs mkdocs-material
+pip3 install mkdocs mkdocs-material mkdocs-include-markdown-plugin
 mkdocs serve
 ```
 

docs/index.md

@@ -1,29 +1,16 @@
-# SignalFlow
+# SignalFlow: Explore sound synthesis and DSP with Python
 
-!!! warning
-    This documentation is a work-in-progress and may have sections that are missing or incomplete.
+SignalFlow is a sound synthesis framework whose goal is to make it quick and intuitive to explore complex sonic ideas. It has a simple Python API, allowing for rapid prototyping in Jupyter notebooks or on the command-line. It comes with over 100 signal processing classes for creative exploration, from filters and delays to FFT-based spectral processing and Euclidean rhythm generators.
 
-SignalFlow is an audio synthesis framework whose goal is to make it quick and intuitive to explore complex sonic ideas. It has a simple and consistent Python API, allowing for rapid prototyping in Jupyter, PyCharm, or on the command-line. It comes with over 100 of built-in node classes for creative exploration.
-
-Its core is implemented in C++11, with cross-platform hardware acceleration.  
+Its core is implemented in efficient C++11, with cross-platform hardware acceleration.  
 
 SignalFlow has robust support for macOS and Linux (including Raspberry Pi), and has work-in-progress support for Windows. The overall project is currently in alpha status, and interfaces may change without warning.
 
-This documentation currently focuses specifically on Python interfaces and examples.
-
-## Overview
-
-At its core, SignalFlow has a handful of key concepts.
-
-- At the top level is the **[AudioGraph](graph/index.md)**, which connects to the system's audio input/output hardware.
-- The graph comprises of a network of **[Nodes](node/index.md)**, each of which performs a single function (for example, generating a cyclical waveform, or filtering an input node). Nodes are connected by input and output relationships: the output of one node may be used to control the frequency of another. As the output of the first node increases, the frequency of the second node increases correspondingly. This modulation is applied on a sample-by-sample basis: all modulation in SignalFlow happens at audio rate.
-- Nodes may have multiple **[inputs](node/inputs.md)**, which determine which synthesis properties can be modulated at runtime.
-- A node can also have **[Buffer](buffer/index.md)** properties, which contain audio waveform data that can be read and written to, for playback or recording of samples. 
-- Nodes can be grouped in a **[Patch](patch/index.md)**, which is a user-defined configuration of nodes. A patch may have one or more named [inputs](patch/inputs.md) that are defined by the user when creating the patch. Patches can be thought of like voices of a synthesizer. A patch can also be set to [automatically remove itself](patch/auto-free.md) from the graph when a specified node's playback is complete, which is important for automatic memory management.
+---
 
 ## Example
 
-Let's take a look at a minimal SignalFlow example. Here, we create and immediately start the `AudioGraph`, construct a stereo sine oscillator, connect the oscillator to the graph's output, and run the graph indefinitely.
+Let's take a look at a minimal SignalFlow example. Here, we create and immediately start the `AudioGraph`, construct a stereo sine oscillator with a short envelope, connect the oscillator to the graph's output, and run the graph indefinitely.
 
 ```python
 from signalflow import *
@@ -45,7 +32,7 @@ This demo shows a few syntactical benefits that SignalFlow provides to make it e
 In subsequent examples, we will skip the `import` line and assume you have already imported everything from the `signalflow` namespace.
 
 !!! info
-    If you want to keep your namespaces better separated, you might want to do something like the below.
+    If you want to enforce separation of namespaces, you might want to do something like the below.
     ```python
     import signalflow as sf
 
@@ -54,6 +41,20 @@ In subsequent examples, we will skip the `import` line and assume you have alrea
     ...
     ```
 
+---
+
+## Overview
+
+At its core, SignalFlow has a handful of key concepts.
+
+- At the top level is the **[AudioGraph](graph/index.md)**, which connects to the system's audio input/output hardware.
+- The graph comprises of a network of **[Nodes](node/index.md)**, each of which performs a single function (for example, generating a cyclical waveform, or filtering an input node). Nodes are connected by input and output relationships: the output of one node may be used to control the frequency of another. As the output of the first node increases, the frequency of the second node increases correspondingly. This modulation is applied on a sample-by-sample basis: all modulation in SignalFlow happens at audio rate.
+- Nodes may have multiple **[inputs](node/inputs.md)**, which determine which synthesis properties can be modulated at runtime.
+- A node can also have **[Buffer](buffer/index.md)** properties, which contain audio waveform data that can be read and written to, for playback or recording of samples. 
+- Nodes can be grouped in a **[Patch](patch/index.md)**, which is a user-defined configuration of nodes. A patch may have one or more named [inputs](patch/inputs.md) that are defined by the user when creating the patch. Patches can be thought of like voices of a synthesizer. A patch can also be set to [automatically remove itself](patch/auto-free.md) from the graph when a specified node's playback is complete, which is important for automatic memory management.
+
+---
+
 ## Documentation
 
 - [Installation](getting-started.md)

docs/installation/command-line-generic.md

@@ -0,0 +1,73 @@
+---
+
+## 1. Set up a virtual environment
+
+Creating a new virtual environment for SignalFlow minimises the chances of conflict with other local Python installs.
+
+```
+python3 -m venv signalflow-env
+source signalflow-env/bin/activate
+```
+
+---
+
+## 2. Install SignalFlow
+
+Installing SignalFlow with `pip`:
+
+```shell
+pip3 install signalflow
+```
+
+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
+```
+
+---
+
+## 4. Hello, world
+
+In your text editor, create a new `.py` file containing the below code:
+
+```python
+from signalflow import *
+
+graph = AudioGraph()
+sine = SineOscillator([440, 880])
+envelope = ASREnvelope(0.1, 0.1, 0.5)
+output = sine * envelope * 0.1
+output.play()
+graph.wait()
+```
+
+When you run the script, you should hear a short stereo "ping".
+
+---
+
+## 5. (Optional) Interactive notebooks in Jupyter
+
+A nice way to experiment with SignalFlow is by using [Jupyter](https://jupyter.org/) interactive notebooks.
+
+Install Jupyter and register this virtual environment as a Jupyter kernel: 
+
+```shell
+pip3 install jupyter
+python3 -m ipykernel install --name signalflow-env
+```
+
+Open a Jupyter notebook:
+
+```
+jupyter notebook
+```
+

docs/installation/index.md

@@ -0,0 +1,31 @@
+# Getting started
+
+## Requirements
+
+SignalFlow supports macOS, Linux (including Raspberry Pi), and has alpha support for Windows. 
+
+## Installation
+
+---
+
+### macOS
+
+If you are an existing Python user and confident with the command line:
+
+[macOS: Install from the command line](macos/command-line.md){ .md-button }
+
+If you're new to Python or getting started from scratch: 
+
+[macOS: Easy install with Visual Studio Code](macos/easy.md){ .md-button } 
+
+---
+
+### Linux
+
+[Linux: Install from the command line](linux/command-line.md){ .md-button }
+
+---
+
+## Examples
+
+[Several example scripts](https://github.com/ideoforms/signalflow/tree/master/examples) are included within the repo, covering simple control and modulation, FM synthesis, sample granulation, MIDI control, chaotic functions, etc.

docs/installation/linux/command-line.md

@@ -0,0 +1,17 @@
+# SignalFlow: Command-line installation for Linux
+
+SignalFlow currently supports Linux x86_64 and Raspberry Pi.
+
+These instructions assume you have a working version of Python 3.8+.
+
+{%
+   include-markdown "installation/command-line-generic.md"
+%}
+
+---
+
+{%
+   include-markdown "installation/next-steps.md"
+%}
+
+---

docs/installation/macos/command-line.md

@@ -2,36 +2,14 @@
 
 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
+{%
+   include-markdown "installation/command-line-generic.md"
+%}
 
-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) are included within the repo, covering simple control and modulation, FM synthesis, sample granulation, MIDI control, chaotic functions, etc.
+{%
+   include-markdown "installation/next-steps.md"
+%}
+
+---

docs/installation/macos/easy.md

@@ -4,12 +4,16 @@ The simplest way to start exploring SignalFlow is with the free [Visual Studio C
 
 You'll only need to do this installation process once. Once setup, experimenting with SignalFlow is as simple as opening Visual Studio Code.  
 
+---
+
 ## 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.
@@ -18,6 +22,8 @@ Download and install the latest version of Visual Studio Code.
 
 Once installed, open `Applications` and run `Visual Studio Code`.
 
+---
+
 ## 3. Install the Python and Jupyter extensions
 
 Visual Studio Code requires extensions to be installed to handle Python and Jupyter files.
@@ -26,6 +32,8 @@ In Visual Studio Code, select the `Extensions` icon from in the far-left column
 
 Once installation has finished, close the `Extensions` tab.
 
+---
+
 ## 4. Create a new workspace
 
 In Visual Studio code, create a new folder to contain your new SignalFlow project:
@@ -39,10 +47,14 @@ In Visual Studio code, create a new folder to contain your new SignalFlow projec
 !!! warning "Trusted workspaces"
     If Visual Studio asks "Do you trust the authors of the files in this folder?", select "Yes, I trust the authors". This is a security mechanism to protect you against untrusted third-party code.
 
+---
+
 ## 5. Create a notebook
 
 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. 
@@ -59,6 +71,8 @@ When the setup is complete, the button in the top right should change to say `.v
 !!! info
     New notebooks created within this workspace will share the same Python virtual environment.  
 
+---
+
 ## 7. Install SignalFlow
 
 In the first block, copy and paste the below:
@@ -71,6 +85,8 @@ To run the cell, press `^↵` (control-enter). After a minute, you should see so
 
 You're now all set to start writing code!
 
+---
+
 ## 8. Start writing code
 
 In a Jupyter interactive notebook, you can write and run multi-line blocks of Python code. Press `enter` to edit the cell, delete its contents, and paste the below.    
@@ -88,6 +104,8 @@ Press `^↵` (control-enter) to run the cell. You should see "Hello world!" appe
     - 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)
 
+---
+
 ## 9. SignalFlow: Import the library and start audio processing 
 
 Clear the first cell, and replace it with:
@@ -108,6 +126,8 @@ This will create and start a new global audio [processing graph](../../graph/ind
 
 This also needs to be run once per session. In fact, only one global `AudioGraph` object can be created.  
 
+---
+
 ## 10. SignalFlow: Make some sound
 
 We're finally ready to make some noise!
@@ -141,4 +161,12 @@ Finally, to stop the playback:
 
 ```python
 output.stop()
-```
+```
+
+---
+
+{%
+   include-markdown "installation/next-steps.md"
+%}
+
+---

docs/installation/next-steps.md

@@ -0,0 +1,5 @@
+## Next steps
+
+ - **Examples**: [Several example scripts](https://github.com/ideoforms/signalflow/tree/master/examples) are available for SignalFlow, covering simple control and modulation, FM synthesis, sample granulation, MIDI control, chaotic functions, etc.
+ - **Configuration**: To configure your audio hardware, see [AudioGraph configuration](../graph/config.md).
+ - **Tutorials**: Coming soon