Made changes to docs relating to Alex Harkers email.

src/sppysound/docs/api.rst

@@ -1,5 +1,9 @@
 API
 ===
+This section contains the details of the underlying code used to create the
+concatenator script. This is included so that developer may use the library for
+further work in this area and aims to provide a complete description of
+functions and class structures in an easy to use format.
 
 -------------------
 AudioFile Class

src/sppysound/docs/descriptor_defs.rst

@@ -2,6 +2,11 @@
 
 Audio Descriptor Definitions
 ============================
+This section describes the audio descriptors used for analysing chacteristics
+of the audio files. Each descriptor is used for measuring a specific
+characteristic and multiple descriptors are combined to match grains based on
+the amalgamation of these measurements. For example, Using the F0 and RMS
+descriptors would match audio based on it's pitch and energy.
 
 Centroid
 ~~~~~~~~~~~~~~~~~

src/sppysound/docs/examples.rst

@@ -1,6 +1,10 @@
 API Usage Examples
 ==================
 
+This section aims to give use case examples for the API. This shows how the
+code can be used to create a python script similar to that of the concatenator
+script.
+
 WARNING: As examples use the same files, only one notebook can be run at a
 time. Make sure one notebook has been closed and halted before starting the
 next.

src/sppysound/docs/index.rst

@@ -11,13 +11,25 @@ audio files based on audio database analysis.
 
 .. image:: Concatenator_diagram_scaled_small.jpg
     :align: center
+    :scale: 100%
 
 This script was developed to explore the creative potential of combining
 short-time audio analyses with granular synthesis, to synthesize perceptually
 related representations of target audio files. Through use of analysed
 databases of varying sizes, an output can be generated that represents a mix of
 the spectral and temporal features of the original target sound and the corpus
-of source sounds from the database.
+of source sounds.
+
+To achieve this, a technique known as "concatenative synthesis" is used. This
+form of synthesis combines the ability to window and join small segments of
+sound to create a new sound (a process known as granular synthesis), with audio
+analysis techniques capable of describing a sound in order to differentiate it
+from others. By analysing small segments in a target sound for their perceptual
+characteristics (such as pitch, timbre and loudness), it is then possible to
+compare these segments to a collection of source sounds to find perceptually
+similar segments. From this, the most perceptually similar matches can be taken
+and joined using granular synthesis techniques in order to achieve the final
+result.
 
 
 .. toctree::

src/sppysound/docs/installation.rst

@@ -1,6 +1,12 @@
 Installation
 ============
 
+This section provides installation instructions for installing the concatenator
+project on your system. There are alternative methods that will most likely
+work for installing both the project and many of it's dependencies,  however
+the method shown below has been tested and is therefore the most reliable
+method for installing this project.
+
 Prerequesites
 -------------
 

src/sppysound/docs/tutorial.rst

@@ -9,6 +9,36 @@ folder root.
 Getting Started
 ---------------
 
+All operations are performed through use of the ./concatenator script. It is
+designed to intuitively search the locations provided as arguments, create any
+analyses that are needed (and do not already exist) automatically, and
+match/synthesize results all through one interface.
+
+This allows the user to simply supply three arguments:
+
+- A source directory
+- A target directory
+- An output directory
+
+The script will then search these for any analyses that have been created
+previously, create any new analyses that haven't and generate results using the
+default settings. 
+
+An example command call might look something like this:
+
+.. code:: bash
+
+    ./concatenator /path/to/source_db /path/to/target_db /path/to/output_db
+
+This will recursively search these folder and organize audio found so that it
+can be used as part of the database. 
+
+Note: If further audio need to be added after having run the script, simply add
+it anywhere in the folder and it will be added to the database on the next run.
+
+Detailed Usage
+--------------
+
 To view all available options simply run:
 
 .. code:: bash
@@ -121,18 +151,18 @@ for generating the databases and storing analysis data. Symbolic links are
 created, referencing the original audio files without moving them.  This allows
 large databases to be used in place without copying or moving it's content.
 
-Alternatively, databases can be generated in place by ommiting the ``--src_db`` and
-``--tar_db`` flags. this will create the database directory structure directly in
+Alternatively, databases can be generated in place by omitting the ``--src_db`` and
+``--tar_db`` flags. This will create the database directory structure directly in
 the directories provided as source and target.
 
 The ``--copy`` flag can be used in conjunction with these flags in order to create
 actual copies of the audio files at the destinations. This allows for the
-creation of partable databases that can moved to other machines without
+creation of portable databases that can moved to other machines without
 breaking links to the original files. (Any pre-existing symbolic links will be
 overwritten with hard copies when using this option.)
 
-Configuration Flags
--------------------
+Parameter Configuration Flags
+-----------------------------
 For quick modification of analysis parameters, parameter flags can be specified
 directly when calling the script. For example:
 
@@ -202,12 +232,12 @@ each parameter. The default config.py file looks like this:
 
     database = {
         # Enables creation of symbolic links to files not in the database rather
-        # than making pysical copies.
+        # than making physical copies.
         "symlink": True
     }
 
-    # Sets the weighting for each analysis. a higher weighting gives an analysis
-    # higher presendence when finding the best matches.
+    # Sets the weighting for each analysis. A higher weighting gives an analysis
+    # higher precedence when finding the best matches.
     matcher_weightings = {
         "f0" : 1.,
         "spccntr" : 1.,
@@ -294,7 +324,7 @@ each parameter. The default config.py file looks like this:
 
 .. _usage:
 
-concatenate.py Script Usage
+concatenate.py Script Flags
 ---------------------------
 -h, --help            show help message and exit
 
@@ -374,7 +404,7 @@ concatenate.py Script Usage
 
 --rematch             Force re-matching, overwriting any existing match data
 
---enforcef0           This flag enables pitch shifting of matched grainsto
+--enforcef0           This flag enables pitch shifting of matched grains to
                       better match the target.
                       
 --enforcerms          This flag enables scaling of matched grains to better