update docs

docs/README.md

@@ -3,15 +3,21 @@
 ## Documentation URL: [https://nkululeko.readthedocs.io/en/latest/](https://nkululeko.readthedocs.io/en/latest/)
 
 ## How to run locally
+
 ```bash
 # Install requirements (from docs directory)
 $ pip install -r requirements.txt
 $ make html
 ```
 
-And then check the built HTML in `build/html/index.html`
+It assumed that the current working directory is `docs/` instead of Nkululeko
+parent directory. Otherwise, it will install requirements for Nkululeko development,
+not for building the documentation.
+
+After that, check the built HTML in `build/html/index.html`
 
 ```bash
-$ firefox build/html/index.html
+firefox build/html/index.html
 ```
-If found any issues, please report them [here](https://github.com/felixbur/nkululeko/issues).
+
+If found any issues, please report them [here](https://github.com/felixbur/nkululeko/issues).

docs/source/demo.md

@@ -1,4 +1,4 @@
-# How to test model with nkululeko.demo
+# Demo module
 
 Nkululeko has `demo` module to either test the built model with an audio file,
 a list of audio files, or even live streaming from your microphone!
@@ -12,10 +12,10 @@ Let's recap the concept of train/dev/test splits:
 Using machine learning (like SVM or XGB), usually we only need train and test.
 Using neural networks or deep learning (like MLP or CNN), we need train, dev, and test.
 
-In this tutorial, we split the use case of `demo` module into two:
+In this tutorial, we split the use case of `demo` module into two:  
 (1) predicting audio file or
 live streaming from microphone and  
-(2) predicting a list of audio files.
+(2) predicting a list of audio files.  
 
 Let's start case by case.
 
@@ -72,7 +72,7 @@ DONE
 
 The example of CSV file for prediction is given below. You can submit it for a such challange.
 
-```csv
+```
 file,angry,happy,neutral,sad,predicted
 ./Actor_21/03-01-07-01-01-01-21.wav,0.314,0.315,0.038,0.332,sad
 ./Actor_21/03-01-06-01-02-02-21.wav,0.314,0.313,0.041,0.332,sad

docs/source/hello_world_aud.md

@@ -1,4 +1,4 @@
-# Hello world!
+# Hello world [AUDFORMAT]
 
 Here is a hello world of using Nkululeko using dataset in [audformat](https://audeering.github.io/audformat/). This hello world is also
 available in [Google
@@ -42,4 +42,4 @@ type = ['os']
 [MODEL]
 type = xgb
 [PLOT]
-```
+```

docs/source/hello_world_csv.md

@@ -1,11 +1,11 @@
-# Hello World with Pre-processed CSV Dataset
+# Hello World with [CSV]
 
-In the previous tutorial, we learned how to use Nkululeko with audformat dataset. 
+In the previous tutorial, we learned how to use Nkululeko with audformat dataset.
 Since most dataset are not in audformat, we will learn how to use Nkululeko with pre-processed CSV dataset.
 
-## Dataset Location 
+## Dataset Location
 
-The dataset is assumed to be located in the `data` directory under `Nkululeko` root directory. The best practice is to store dataset in `/data/` or `/home/$USER/data/` directory and then make a symbolic link to each dataset in the Nkululeko `data` directory. 
+The dataset is assumed to be located in the `data` directory under `Nkululeko` root directory. The best practice is to store dataset in `/data/` or `/home/$USER/data/` directory and then make a symbolic link to each dataset in the Nkululeko `data` directory.
 Here the example of downloading dataset into its location, doing pre-processing and running the experiment. The main idea of the pre-processing is to convert the dataset into the format that Nkululeko can understand. Usually, the pre-processing is done by running the `process_database.py` script. You can learn more about the pre-processing in each dataset directory (`/nkululeko/data`).
 
 Let's start with the ravdess directory.
@@ -16,12 +16,14 @@ database to nkululeko.
 We used the version downloadable from [Zenodo](https://zenodo.org/record/1188976)
 
 Download and unzip the file Audio_Speech_Actors_01-24.zip
+
 ```bash
-$ wget https://zenodo.org/record/1188976/files/Audio_Speech_Actors_01-24.zip
-$ unzip Audio_Speech_Actors_01-24.zip
+wget https://zenodo.org/record/1188976/files/Audio_Speech_Actors_01-24.zip
+unzip Audio_Speech_Actors_01-24.zip
 ```
 
 Run the file
+
 ```bash
 python3 process_database.py
 ```
@@ -40,4 +42,4 @@ python3 -m nkululeko.nkululeko --config data/ravdess/exp_ravdess_os_xgb.ini
 
 Check the results in the results folder under Nkululeko parent directory.
 
-Just simple as that. Check your results and play with some parameters. If facing any problem, please open an issue in [our github](https://github.com/felixbur/nkululeko/).
+Just simple as that. Check your results and play with some parameters. If facing any problem, please open an issue in [our github](https://github.com/felixbur/nkululeko/).

docs/source/index.rst

@@ -16,19 +16,19 @@ Altogether, this make Nkululeko as a good teaching/learning tool for speaker cha
 The examples only covers some important features of Nkululeko. For more details, please refer to the `Nkululeko Github page <https://felixbur.github.io/nkululeko/>`__ and `Felix's web page <http://blog.syntheticspeech.de/category/nkululeko/>`__. 
 
 .. toctree::
-   :maxdepth: 2
-   :caption: Installation
+   :maxdepth: 1
+   :caption: Installation:
 
    installation
 
 .. toctree::
-   :maxdepth: 2
-   :caption: USAGE
+   :maxdepth: 1
+   :caption: Usage
 
    usage.md
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: INI File 
 
    ini_file.md
@@ -41,21 +41,25 @@ The examples only covers some important features of Nkululeko. For more details,
    hello_world_aud.md
    hello_world_csv.md
    comparing
-
-.. toctree:: 
-   :maxdepth: 2
-   :caption: CLI Reference (modules)
-
-   nkululeko.md
+   experiments.md
    test.md
    demo.md
 
-
 .. toctree::
-   :maxdepth: 1
-   :caption: Function Reference
+   :maxdepth: 2
+   :caption: API Reference
+
+   nkululeko.rst
+   nkululeko.augmenting.rst
+   nkululeko.autopredict.rst
+   nkululeko.data.rst
+   nkululeko.feat_extract.rst
+   nkululeko.losses.rst
+   nkululeko.models.rst
+   nkululeko.reporting.rst
+   nkululeko.segmenting.rst
+   nkululeko.utils.rst
 
-
 
 Indices and tables
 ==================

docs/source/test.md

@@ -1,18 +1,18 @@
-# nkululeko.test
-
-Module for testing the testing known datatast (has labels).  
+# Test module
 
+Module for testing a saved model on known datatast (has labels).  
 
 Usage:  
+
 ```bash
-python -m nkululeko.test --config mycoonfg.ini --outfile myresults.csv
+python -m nkululeko.test --config myconfg.ini --outfile myresults.csv
 ```
 
-
 Example of `INI` file:  
+
 ```ini
 [DATA]
 tests = ['my_testdb']
 my_testdb = /mypath/my_testdb
 ...
-```
+```

nkululeko/autopredict/estimate_snr.py

@@ -1,20 +1,30 @@
 # estimate.snr
-import numpy as np
+"""
+Module for estimating SNR (signal to noise ratio) from an audio signal.
+
+This module provides a class `SNREstimator` which calculates the SNR based on
+the log energy and energy thresholds of the audio signal.
+
+"""
+
+import argparse
+
 import audiofile
 import matplotlib.pyplot as plt
+import numpy as np
 from scipy.signal.windows import hamming
-import argparse
 
 
 class SNREstimator:
-    """Estimate SNR from audio signal using log energy and energy thresholds
+    """Estimate SNR from audio signal using log energy and energy thresholds.
+
     Args:
         input_data (ndarray): Input audio signal
         sample_rate (int): Sampling rate of input audio signal
         window_size (int): Window size in samples
         hop_size (int): Hop size in samples
 
-        Returns:
+    Returns:
         object: SNREstimator object
         estimated_snr (float): Estimated SNR in dB, extracted from SNREstimator.estimate_snr()
 
@@ -34,7 +44,7 @@ def frame_audio(self, signal):
         num_frames = 1 + (len(signal) - self.frame_length) // self.hop_length
         frames = [
             signal[
-                i * self.hop_length : (i * self.hop_length) + self.frame_length
+                i * self.hop_length: (i * self.hop_length) + self.frame_length
             ]
             for i in range(num_frames)
         ]
@@ -54,7 +64,8 @@ def estimate_snr(self):
             for frame in frames
         ]
 
-        energy_threshold_low = np.percentile(log_energies, 25)  # First quartile
+        energy_threshold_low = np.percentile(
+            log_energies, 25)  # First quartile
         energy_threshold_high = np.percentile(
             log_energies, 75
         )  # Third quartile

nkululeko/feat_extract/feats_snr.py

@@ -1,29 +1,35 @@
-""" feats_snr.py
-    Estimate snr (signal to noise ratio as acoustic features)
+""" feats_snr.py is to estimate snr.
+
+SNR (signal to noise ratio) is extracted as acoustic features.
 """
 import os
-from tqdm import tqdm
-import pandas as pd
+
 import audiofile
+import pandas as pd
+from tqdm import tqdm
+
 import nkululeko.glob_conf as glob_conf
-from nkululeko.utils.util import Util
-from nkululeko.feat_extract.featureset import Featureset
 from nkululeko.autopredict.estimate_snr import SNREstimator
+from nkululeko.feat_extract.featureset import Featureset
+from nkululeko.utils.util import Util
 
 
 class SNRSet(Featureset):
     """Class to estimate snr"""
 
     def __init__(self, name, data_df):
         """Constructor."""
+
         super().__init__(name, data_df)
 
     def extract(self):
         """Estimate the features or load them from disk if present."""
+
         store = self.util.get_path("store")
         store_format = self.util.config_val("FEATS", "store_format", "pkl")
         storage = f"{store}{self.name}.{store_format}"
-        extract = self.util.config_val("FEATS", "needs_feature_extraction", False)
+        extract = self.util.config_val(
+            "FEATS", "needs_feature_extraction", False)
         no_reuse = eval(self.util.config_val("FEATS", "no_reuse", "False"))
         if extract or no_reuse or not os.path.isfile(storage):
             self.util.debug("estimating SNR, this might take a while...")
@@ -40,7 +46,8 @@ def extract(self):
                 snr = self.get_snr(signal[0], sampling_rate)
                 snr_series[idx] = snr
             print("")
-            self.df = pd.DataFrame(snr_series.values.tolist(), index=self.data_df.index)
+            self.df = pd.DataFrame(
+                snr_series.values.tolist(), index=self.data_df.index)
             self.df.columns = ["snr"]
             self.util.write_store(self.df, storage, store_format)
             try:
@@ -53,10 +60,11 @@ def extract(self):
 
     def get_snr(self, signal, sampling_rate):
         r"""Estimate SNR from raw audio signal.
+
         Args:
             signal: audio signal
             sampling_rate: sample rate
-        Returns
+        Returns:
             snr: estimated signal to noise ratio
         """
         snr_estimator = SNREstimator(signal, sampling_rate)