Partial edits for generic manual

- Redesigned the installation pages so that they're simpler and have ssub-pages
- added notes to config docs about profiles
- renamed generic recognisers document so that the name makes a better URL compatible file name
- added figure styling so that figures are presented in a nicer manner
- Refactored some of the generic recognisers document (the more general parts) into theory sections)

.vscode/settings.json

@@ -1,16 +1,26 @@
 {
     "cSpell.words": [
-        "Arial",
-        "Ecoacoustics",
-        "Hanning",
-        "Roboto",
-        "Tahoma",
-        "Towsey",
-        "Truskinger",
-        "choco",
-        "docfx",
-        "nyquist",
-        "pwsh",
-        "rects"
-    ]
+      "Arial",
+      "Ecoacoustics",
+      "Hanning",
+      "Roboto",
+      "Tahoma",
+      "Towsey",
+      "Truskinger",
+      "choco",
+      "convolutional",
+      "docfx",
+      "formants",
+      "nyquist",
+      "pwsh",
+      "rects",
+      "resample",
+      "resampling",
+      "wingbeats"
+    ],
+    "triggerTaskOnSave.tasks": {
+      "docs-save-build": [
+        "docs/**"
+      ]
+    }
 }

.vscode/tasks.json

@@ -37,6 +37,19 @@
                 "/consoleloggerparameters:NoSummary"
             ],
             "problemMatcher": "$msCompile"
+        },
+        {
+          "label": "docs-save-build",
+          "command": "docfx",
+          "args": ["build"],
+          "type": "process",
+          "options": {
+            "cwd": "docs"
+          },
+          "runOptions": {
+            "instanceLimit": 1,
+            "runOn": "default"
+          }
         }
     ]
 }

CONTRIBUTING.md

@@ -24,7 +24,7 @@
 - Dates and durations:
     1. **ONLY** format dates in an ISO8601 format
         - a modified ISO8601 format with all punctuation removed is acceptable
-          for file/folder names. Example format string: yyyyMMddTHHmmssZ
+          for file/folder names. Example format string: `yyyyMMddTHHmmssZ`
     1. **ALWAYS** format dates with UTC offset information if available
     1. **PREFER** formatting dates in the UTC timezone
     1. **AVOID** exposing `TimeSpan`s to user facing fields (use seconds instead)
@@ -36,8 +36,6 @@
   and improve on this.  
   [![codecov](https://codecov.io/gh/QutEcoacoustics/audio-analysis/branch/master/graph/badge.svg)](https://codecov.io/gh/QutEcoacoustics/audio-analysis)
 
-
-
 ## Required Software
 
 The **required** software for developing new code (not running the program) includes:

docs/basics/advanced/manual_install.md

@@ -0,0 +1,80 @@
+---
+title: Manual Install
+uid: basics-manual-install
+---
+
+
+## Manual Install
+
+1. Go to our [releases](https://github.com/QutEcoacoustics/audio-analysis/releases) page
+2. Select the version you want to download
+    - Choose the _Latest release_ unless you specifically need features that are 
+      available in a _Pre-release_
+3. Scroll down to the assets section for your chosen release
+4. Download the version of AnalysisPrograms suitable for your computer (see [Choosing the asset](#choosing-the-asset))
+5. Extract the folder
+    - It can be installed in any directory
+    - We typically extract to a directory named `~\AP` or `~/.local/share/AP` on Linux
+6. Make sure any [Prerequisites](#prerequisites) are installed
+7. [Optional] Add the install directory to your `PATH` environment variable
+    - Instructions in the [Path](./path.md) document.
+8. Finally, check the install by running:
+
+Run the following command:
+
+### [Windows Check](#tab/windows)
+
+```powershell
+C:\AP\AnalysisPrograms.exe CheckEnvironment
+```
+
+### [Linux Check](#tab/linux)
+
+```bash
+/AP/AnalysisPrograms CheckEnvironment
+```
+
+### [MacOSX Check](#tab/osx)
+
+```bash
+/AP/AnalysisPrograms CheckEnvironment
+```
+
+***
+
+### Choosing the asset
+
+[!include[<Asset chooser>](<./assetChooser.html>)]
+
+## Prerequisites
+
+### Windows
+
+None. Self contained download.
+
+### MacOSX
+
+None. Self contained download.
+
+### Linux/Unix
+
+The following additional dependencies may be required for Linux/Unix machines:
+
+- **MAYBE**: ffmpeg
+    - a packaged version with AP.exe should work for all platforms except ARM and ARM64
+- **MAYBE**:  wavpack
+- libsox-fmt-all, sox
+- libav-tools (on some distros only, not needed in Ubuntu 18)
+
+## Build Packages
+
+There are two variants of AP.exe:
+
+1. The **Stable** release is well tested used by QUT Ecoacoustics on our servers
+    and is usually a few months old
+2. The **Prerelease** release is automatically built weekly, every Monday. It has more
+    features and bug fixes than the stable release but it also could have more
+    bugs.
+
+You should use the **Stable** release unless there is a recent
+feature implemented or bug fix in the prerelease version that you need.

docs/basics/advanced/path.md

@@ -0,0 +1,119 @@
+---
+title: Adding to PATH
+uid: basics-path
+---
+
+
+## Adding AP.exe to `PATH`
+
+The `PATH` variable is a system wide variable (known as en environment variable)
+that any program can access. The `PATH` variable contains a list of folders that
+your computer can check when it searches for programs to run.
+
+When AP's folder is added to `PATH` you or any program on your computer can
+run _AnalysisPrograms.exe_ without knowing where AP is actually installed.
+
+So instead of needing this:
+
+```powershell
+> C:\Users\Anthony\AP\AnalysisPrograms.exe
+```
+
+You can instead write:
+
+```powershell
+> AnalysisPrograms.exe
+```
+
+### Setup using the installer script
+
+The [automatic installer](../installing.md) will automatically add AP to `PATH` for you.
+
+If you don't want this to happen use the `-DontAddToPath` switch when installing.
+
+### Add to `PATH` manually
+
+### [Windows](#tab/windows)
+
+1. Find where AP is installed on your computer. This will be a directory (folder)
+  where _AnalysisPrograms.exe_ resides.
+2. Open your _System Environment Variables_. You can type some of
+_Edit environment variables for your account_ in the Start Menu search box
+to find the settings.
+3. Choose _Environment Variables..._ in the windows that popped up
+4. In the _user variables_ section, find the _Path_ variable, select it, and then hit the _Edit_ button
+5. Add the directory from step 1 to the end
+    - Ensure a semi-colon (`;`) delimits the new directory from the previous ones, if you're using an older version of Windows
+6. Then click _OK_ or close all windows.
+7. You will have to restart any programs for which you want to see the new value
+
+### [Linux](#tab/linux)
+
+1. Find where AP is installed on your computer. This will be a directory (folder)
+  where _AnalysisPrograms.exe_ resides.
+2. Open or create your `~/.profile` file
+3. Add the following line to the end:
+
+    ```bash
+    PATH=$PATH:<REPLACE-ME>
+    ```
+
+   where you replace the `<REPLACE-ME>` with the directory from step 1.
+4. Close and save the file
+5. Run the same command in your current shell (`PATH=$PATH:<REPLACE-ME>`) to
+  see the change take effect immediately (or restart your shell).
+
+### [MacOSX](#tab/osx)
+
+1. Find where AP is installed on your computer. This will be a directory (folder)
+  where _AnalysisPrograms.exe_ resides.
+2. Open or create your `~/.profile` file
+3. Add the following line to the end:
+
+    ```bash
+    PATH=$PATH:<REPLACE-ME>
+    ```
+
+   where you replace the `<REPLACE-ME>` with the directory from step 1.
+4. Close and save the file
+5. Run the same command in your current shell (`PATH=$PATH:<REPLACE-ME>`) to
+  see the change take effect immediately (or restart your shell).
+
+***
+
+## Aliasing _AnalysisPrograms.exe_ to _AP_
+
+_AnalysisPrograms.exe_ is a long name. Tiring to type, prone to errors.
+It also isn't a good name for a cross-platform program; on Linux and Mac OS it
+is simply _AnalysisPrograms_.
+
+To make it easier for people to experiment with and use _AP_ we aliased (gave
+another name) to _AnalysisPrograms.exe_. We chose `AP`.
+
+So instead of needing this:
+
+```powershell
+> C:\Users\Anthony\AP\AnalysisPrograms.exe
+```
+
+You can instead write (assuming _AnalysisPrograms.exe_ is on PATH):
+
+```powershell
+> AP
+```
+
+### Setup an alias using the installer script
+
+If you have installed AP using the [automatic installer](../installing.md) then
+this alias has already been set up for you!
+
+### Setup an alias manually
+
+This is advanced content.
+
+1. Find the _AP_ installation directory
+2. Create a symbolic link 
+    - Windows: `<INSTALL-DIR>\AP.exe` and `<INSTALL-DIR>\_AnalysisPrograms.exe`
+    - Linux/Mac: `<INSTALL-DIR>/AP` and `<INSTALL-DIR>/_AnalysisPrograms`
+
+You'll need to ensure `<INSTALL-DIR>` in on `PATH`.