Added a ton of documentation

Closes #130

This incorporates @towsey's two manual documents into a docs folder that will eventually be a microsite.

The documentation is far far far from finished - but it is a good a decent start.
Closing #130 because we'll open more specific issues as we go on.

doc/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "cSpell.words": [
+        "Ecoacoustics",
+        "recognizers"
+    ]
+}

doc/README.MD

@@ -0,0 +1,30 @@
+# QUT Ecoacoustics: AnalysisPrograms.exe manual
+
+
+*QUT Ecoacoustics Analysis Programs* is a software package to perform a suite of analyses on audio recordings of the environment. Although the analyses are intended for long-duration recordings (1 – 24 hours approx), in fact they can be performed on any audio file in a format supported by the software. Typically, you would not use the software to analyse recordings shorter than one minute. Currently the software performs:
+
+- calculation of summary and spectral acoustic indices at variable resolutions
+- produces long-duration, false-colour, multi-index spectrograms
+- can calculate critical statistics of annotations downloaded from an Acoustic Workbench
+- is capable of running various acoustic event recognizers
+
+All the analyses are performed by a single executable file, _AnalysisPrograms.exe) (henceforth abbreviated to _AP.exe_), with command-line arguments determining what analyses are to be done and on which files.
+
+## Table of contents
+
+- [FAQ](./faq)
+- [Supported Platforms](./supported_platforms.md)
+- [Downloading and Installing](./installing.md) AnalysisPrograms.exe
+- [Introduction to running commands](./cli.md)
+- [Actions](./actions.md)
+- [Config Files](./config_files.md)
+- [Supported Audio Formats](./formats.md)
+- [List of Analyses](./analyses/)
+- [Workflows](./workflows)
+- [TODO: Citing the software]
+
+Supplementary:
+
+- [Version Numbers](./versioning.md)
+- [TODO: Log Files]
+- [Code paths](./code_paths) that explain how code is executed

doc/actions.md

@@ -0,0 +1,41 @@
+# Actions
+
+## Types
+
+There are, in broad terms, these types of sub-programs:
+
+-   Main actions
+    -   Process large amounts of information (like `audio2csv`)
+-   Development / small scale actions
+    -   Small data / development entry points
+    -   `eventrecognizer` which is a generic program for testing different recognizers
+-   Utility actions
+    -   `DummyAnalyser` - uses CPU for a while and does nothing useful
+    -   `audiocutter` - cuts and converts long audio files up
+-   Meta actions
+    -   help and documentation usage (`help` & `list`)
+    -   `analysesavailable`
+
+
+## Actions
+
+
+### Analyze Long Recordings
+
+Processes large audio recording with the specified analysis. Can run recognizers, calculate indices, or do other things, for very long recordings.
+
+See [details on Analyze Long Recordings](./actions/analyze_long_recordings.md)
+
+### Colour Spectrogram
+
+This action produces a single false-colour (FC) spectrogram, taking as input the spectral indices produced by the _Acoustic Indices_ analysis on a single audio file.
+
+See [details on Colour Spectrogram](./actions/colour_spectrogram.md)
+
+### Concatenate Index Files
+
+This action joins together the results of several _Acoustic Indices_ analysis
+result sets to produce data and images for 24-hour blocks of data.
+
+See [details on Concatenate Index Files](./actions/concatenate_index_files.md)
+

doc/actions/analyze_long_recording.md

@@ -0,0 +1,65 @@
+# Analyze Long Recordings (audio2csv)
+
+Action      | audio2csv
+Config file | \<any compatible config file\>
+
+This action applies an analysis to a long recording. It works well with recordings
+that are up 1440 minutes long.
+
+This action takes a single long-duration audio recording as input, splits it into segments and calculates results and writes the output to several .csv files.
+This analysis process supports **parallel** processing.
+
+Analyze long recordings can run many types of analyses. The provided config file
+determines what analyses is run.
+
+To see a list of all analyses that can be used by _audio2csv_, execute:
+
+```
+AnalysisPrograms.exe analysesavailable
+```
+
+As the action name implies, the output of this analysis is a set of CSV files that can contain:
+
+- recognized acoustic events
+- summary indices
+- spectral indices
+
+## Usage
+
+This section describes the command line arguments required to, for example, calculate acoustic indices derived from a single audio file.
+
+To run the action, type:
+
+```
+$ AnalysisPrograms.exe audio2csv <options...>
+```
+
+Here is an example of a command line with abbreviated path names:
+
+```
+$ AnalysisPrograms.exe audio2csv -input "audioPath\\fileName.wav"  -output "outputPath\\directoryName" -config "configPath\\fileName.yml"
+```
+
+The above three paths are required arguments (the program will return a fatal error if they are not found on the command line). 
+
+A REMINDER: All path names should be double quoted, BUT make sure you use plain double quotes (`".."`) and NOT so called _smart quotes_ (`“..”`). The paths to directories should *never* end in a forward-slash or back-slash.
+
+## Options
+
+Typically, analyses will also include optional arguments that take default values if they are not found on the command line. 
+
+Here is more detail about the command line options:
+
+-   `-input`: The path to the audio file to process
+-   `-output`: The output will be placed the directory provided
+-   `-config`:
+    - **IMPORTANT**: The config file chosen will determine the analysis that is run
+    - The config file contain parameters that unique for the chosen analysis
+    - If the config file cannot be found, a fatal error will result
+    - Typically, if a required parameter is not found in the config file, a default value will be used or in certain cases, a fatal error may result.
+-   `-Channels`:
+    - The default value is `null` (not specified) which means that all channels are used.
+    - _AP.exe_ can process files with up to 8 channels.
+    - [TODO: CHECK THIS] Channels are numbered, 0, 1, 2, … In the usual case of stereo, left channel = 0 and right channel = 1. Note that, although the software should be able to accept recordings where channel number is greater than two, this use has not been debugged and results are undefined.
+-   `-MixDownToMono`: The default value is `true`. Typically, indices are calculated on the mixed down waveform.
+-   `-Parallel`: If you have access to a multi-core CPU you can set this option to true. Otherwise, the segments will be cut and analysed in sequence.