From d22d4c7646937728fe73612db3da841f1ed347f7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20Bla=C3=9F?= <michael.blass@uni-hamburg.de>
Date: Fri, 19 Mar 2021 14:18:47 +0100
Subject: [PATCH] Doc updates

---
 README.md                                     | 10 ++++--
 docs/Makefile                                 |  5 ++-
 docs/source/conf.py                           | 34 +++++++++++++------
 docs/source/download.rst                      |  4 +--
 docs/source/framework.rst                     | 15 +++++---
 .../{ => generated}/api/apollon.aplot.rst     |  0
 .../{ => generated}/api/apollon.audio.rst     |  0
 .../{ => generated}/api/apollon.container.rst |  0
 .../{ => generated}/api/apollon.datasets.rst  |  0
 .../{ => generated}/api/apollon.fractal.rst   |  0
 .../api/apollon.hmm.poisson.rst               |  0
 .../{ => generated}/api/apollon.hmm.rst       |  0
 .../api/apollon.hmm.utilities.rst             |  0
 .../{ => generated}/api/apollon.io.io.rst     |  0
 .../{ => generated}/api/apollon.io.json.rst   |  0
 .../source/{ => generated}/api/apollon.io.rst |  0
 .../{ => generated}/api/apollon.onsets.rst    |  0
 docs/source/{ => generated}/api/apollon.rst   |  0
 .../{ => generated}/api/apollon.segment.rst   |  0
 .../api/apollon.signal.container.rst          |  0
 .../api/apollon.signal.critical_bands.rst     |  0
 .../api/apollon.signal.features.rst           |  0
 .../api/apollon.signal.filter.rst             |  0
 .../{ => generated}/api/apollon.signal.rst    |  0
 .../api/apollon.signal.spectral.rst           |  0
 .../api/apollon.signal.tools.rst              |  0
 .../api/apollon.som.datasets.rst              |  0
 .../api/apollon.som.defaults.rst              |  0
 .../api/apollon.som.neighbors.rst             |  0
 .../{ => generated}/api/apollon.som.plot.rst  |  0
 .../{ => generated}/api/apollon.som.rst       |  0
 .../{ => generated}/api/apollon.som.som.rst   |  0
 .../api/apollon.som.topologies.rst            |  0
 .../api/apollon.som.utilities.rst             |  0
 .../{ => generated}/api/apollon.tools.rst     |  0
 .../{ => generated}/api/apollon.types.rst     |  0
 docs/source/{ => generated}/api/modules.rst   |  0
 docs/source/index.rst                         |  6 ++--
 docs/source/install.rst                       |  8 ++---
 src/apollon/__init__.py                       |  2 +-
 src/apollon/signal/__init__.py                | 15 ++++++++
 41 files changed, 71 insertions(+), 28 deletions(-)
 rename docs/source/{ => generated}/api/apollon.aplot.rst (100%)
 rename docs/source/{ => generated}/api/apollon.audio.rst (100%)
 rename docs/source/{ => generated}/api/apollon.container.rst (100%)
 rename docs/source/{ => generated}/api/apollon.datasets.rst (100%)
 rename docs/source/{ => generated}/api/apollon.fractal.rst (100%)
 rename docs/source/{ => generated}/api/apollon.hmm.poisson.rst (100%)
 rename docs/source/{ => generated}/api/apollon.hmm.rst (100%)
 rename docs/source/{ => generated}/api/apollon.hmm.utilities.rst (100%)
 rename docs/source/{ => generated}/api/apollon.io.io.rst (100%)
 rename docs/source/{ => generated}/api/apollon.io.json.rst (100%)
 rename docs/source/{ => generated}/api/apollon.io.rst (100%)
 rename docs/source/{ => generated}/api/apollon.onsets.rst (100%)
 rename docs/source/{ => generated}/api/apollon.rst (100%)
 rename docs/source/{ => generated}/api/apollon.segment.rst (100%)
 rename docs/source/{ => generated}/api/apollon.signal.container.rst (100%)
 rename docs/source/{ => generated}/api/apollon.signal.critical_bands.rst (100%)
 rename docs/source/{ => generated}/api/apollon.signal.features.rst (100%)
 rename docs/source/{ => generated}/api/apollon.signal.filter.rst (100%)
 rename docs/source/{ => generated}/api/apollon.signal.rst (100%)
 rename docs/source/{ => generated}/api/apollon.signal.spectral.rst (100%)
 rename docs/source/{ => generated}/api/apollon.signal.tools.rst (100%)
 rename docs/source/{ => generated}/api/apollon.som.datasets.rst (100%)
 rename docs/source/{ => generated}/api/apollon.som.defaults.rst (100%)
 rename docs/source/{ => generated}/api/apollon.som.neighbors.rst (100%)
 rename docs/source/{ => generated}/api/apollon.som.plot.rst (100%)
 rename docs/source/{ => generated}/api/apollon.som.rst (100%)
 rename docs/source/{ => generated}/api/apollon.som.som.rst (100%)
 rename docs/source/{ => generated}/api/apollon.som.topologies.rst (100%)
 rename docs/source/{ => generated}/api/apollon.som.utilities.rst (100%)
 rename docs/source/{ => generated}/api/apollon.tools.rst (100%)
 rename docs/source/{ => generated}/api/apollon.types.rst (100%)
 rename docs/source/{ => generated}/api/modules.rst (100%)

diff --git a/README.md b/README.md
index f8efc6f..7efe7e2 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,14 @@
 # Apollon
-Apollon is a framework for modelling audio feature time series. It comprises
-* low-level audio feature extraction
-* Hidden-Markov Models
+Apollon is a Python framework for audio feature extraction and music similarity estimation. It 
+includes subpackages for
+
+* Audio feature extraction
+* Hidden Markov Models
 * Self-Organizing Map
 
 ## 1. Installation
+### 1.1 Install from PyPi
+The latest version of apollon is available on PyPi. 
 Download apollon or clone this repository. Navigate the package's root directory
 and install apollon using pip.
 ```
diff --git a/docs/Makefile b/docs/Makefile
index 69fe55e..5a1a12e 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -7,6 +7,9 @@ SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = build
 
+clean:
+	rm -rf build/* source/api/*
+
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@@ -16,4 +19,4 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 61a6c46..ea543be 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -12,39 +12,48 @@ import sphinx_rtd_theme
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+sys.path.insert(0, os.path.abspath('./src/apollon/'))
 
 
 # -- Project information -----------------------------------------------------
 
-project = 'Apollon'
-copyright = '2019, Michael Blaß'
+project = 'apollon'
 author = 'Michael Blaß'
+copyright = '2019, Michael Blaß'
 
 # The full version, including alpha/beta/rc tags
+version = '0.1'
 release = '0.1.3'
-version = '0.1.3'
+
+master_doc = 'index'
 
 
 # -- General configuration ---------------------------------------------------
+source_suffix = {'.rst': 'restructuredtext'}
+language = 'en'
+#nitpicky = True
+numfig = True
+pygments_style = 'sphinx'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinxcontrib.apidoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
+    'sphinxcontrib.apidoc',
     'sphinx_rtd_theme']
 
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ['_build', '.DS_Store']
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -60,10 +69,15 @@ html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
 
 
+# -- Options for autosummary ------------------------------------------------
+#
+
+
+
 # -- Options for apidoc -----------------------------------------------------
 #
 apidoc_module_dir = '../../src/apollon'
-apidoc_output_dir = 'api'
+apidoc_output_dir = 'generated/api'
 apidoc_separate_modules = True
 apidoc_module_first = True
 apidoc_full = True
@@ -73,7 +87,7 @@ apidoc_full = True
 #
 napoleon_google_docstring = True
 napoleon_numpy_docstring = False
-napoleon_include_init_with_doc = True
+napoleon_include_init_with_doc = False
 napoleon_include_private_with_doc = False
 napoleon_include_special_with_doc = False
 napoleon_use_ivar = True
diff --git a/docs/source/download.rst b/docs/source/download.rst
index c10742c..65a7258 100644
--- a/docs/source/download.rst
+++ b/docs/source/download.rst
@@ -1,6 +1,6 @@
+****************************************
 Download
-***************************************
-
+****************************************
 You can either download the source code from the `apollon GitHub repository`_
 or clone it directly with
 
diff --git a/docs/source/framework.rst b/docs/source/framework.rst
index 0acad7e..f7741e4 100644
--- a/docs/source/framework.rst
+++ b/docs/source/framework.rst
@@ -1,16 +1,23 @@
+****************************************
 Framework
-***************************************
+****************************************
+
+.. _fw-fe:
 
 Audio Feature Extraction
-=======================================
+========================================
 Extract some of the most common low-level audio feauters.
 
 
+.. _fw-hmm:
+
 Hidden Markov Model
-=======================================
+========================================
 Estimate Poisson-distributed Hidden Markov Models.
 
 
+.. _fw-som:
+
 Self-Organizing Map
-=======================================
+========================================
 Train some Self-organizing maps.
diff --git a/docs/source/api/apollon.aplot.rst b/docs/source/generated/api/apollon.aplot.rst
similarity index 100%
rename from docs/source/api/apollon.aplot.rst
rename to docs/source/generated/api/apollon.aplot.rst
diff --git a/docs/source/api/apollon.audio.rst b/docs/source/generated/api/apollon.audio.rst
similarity index 100%
rename from docs/source/api/apollon.audio.rst
rename to docs/source/generated/api/apollon.audio.rst
diff --git a/docs/source/api/apollon.container.rst b/docs/source/generated/api/apollon.container.rst
similarity index 100%
rename from docs/source/api/apollon.container.rst
rename to docs/source/generated/api/apollon.container.rst
diff --git a/docs/source/api/apollon.datasets.rst b/docs/source/generated/api/apollon.datasets.rst
similarity index 100%
rename from docs/source/api/apollon.datasets.rst
rename to docs/source/generated/api/apollon.datasets.rst
diff --git a/docs/source/api/apollon.fractal.rst b/docs/source/generated/api/apollon.fractal.rst
similarity index 100%
rename from docs/source/api/apollon.fractal.rst
rename to docs/source/generated/api/apollon.fractal.rst
diff --git a/docs/source/api/apollon.hmm.poisson.rst b/docs/source/generated/api/apollon.hmm.poisson.rst
similarity index 100%
rename from docs/source/api/apollon.hmm.poisson.rst
rename to docs/source/generated/api/apollon.hmm.poisson.rst
diff --git a/docs/source/api/apollon.hmm.rst b/docs/source/generated/api/apollon.hmm.rst
similarity index 100%
rename from docs/source/api/apollon.hmm.rst
rename to docs/source/generated/api/apollon.hmm.rst
diff --git a/docs/source/api/apollon.hmm.utilities.rst b/docs/source/generated/api/apollon.hmm.utilities.rst
similarity index 100%
rename from docs/source/api/apollon.hmm.utilities.rst
rename to docs/source/generated/api/apollon.hmm.utilities.rst
diff --git a/docs/source/api/apollon.io.io.rst b/docs/source/generated/api/apollon.io.io.rst
similarity index 100%
rename from docs/source/api/apollon.io.io.rst
rename to docs/source/generated/api/apollon.io.io.rst
diff --git a/docs/source/api/apollon.io.json.rst b/docs/source/generated/api/apollon.io.json.rst
similarity index 100%
rename from docs/source/api/apollon.io.json.rst
rename to docs/source/generated/api/apollon.io.json.rst
diff --git a/docs/source/api/apollon.io.rst b/docs/source/generated/api/apollon.io.rst
similarity index 100%
rename from docs/source/api/apollon.io.rst
rename to docs/source/generated/api/apollon.io.rst
diff --git a/docs/source/api/apollon.onsets.rst b/docs/source/generated/api/apollon.onsets.rst
similarity index 100%
rename from docs/source/api/apollon.onsets.rst
rename to docs/source/generated/api/apollon.onsets.rst
diff --git a/docs/source/api/apollon.rst b/docs/source/generated/api/apollon.rst
similarity index 100%
rename from docs/source/api/apollon.rst
rename to docs/source/generated/api/apollon.rst
diff --git a/docs/source/api/apollon.segment.rst b/docs/source/generated/api/apollon.segment.rst
similarity index 100%
rename from docs/source/api/apollon.segment.rst
rename to docs/source/generated/api/apollon.segment.rst
diff --git a/docs/source/api/apollon.signal.container.rst b/docs/source/generated/api/apollon.signal.container.rst
similarity index 100%
rename from docs/source/api/apollon.signal.container.rst
rename to docs/source/generated/api/apollon.signal.container.rst
diff --git a/docs/source/api/apollon.signal.critical_bands.rst b/docs/source/generated/api/apollon.signal.critical_bands.rst
similarity index 100%
rename from docs/source/api/apollon.signal.critical_bands.rst
rename to docs/source/generated/api/apollon.signal.critical_bands.rst
diff --git a/docs/source/api/apollon.signal.features.rst b/docs/source/generated/api/apollon.signal.features.rst
similarity index 100%
rename from docs/source/api/apollon.signal.features.rst
rename to docs/source/generated/api/apollon.signal.features.rst
diff --git a/docs/source/api/apollon.signal.filter.rst b/docs/source/generated/api/apollon.signal.filter.rst
similarity index 100%
rename from docs/source/api/apollon.signal.filter.rst
rename to docs/source/generated/api/apollon.signal.filter.rst
diff --git a/docs/source/api/apollon.signal.rst b/docs/source/generated/api/apollon.signal.rst
similarity index 100%
rename from docs/source/api/apollon.signal.rst
rename to docs/source/generated/api/apollon.signal.rst
diff --git a/docs/source/api/apollon.signal.spectral.rst b/docs/source/generated/api/apollon.signal.spectral.rst
similarity index 100%
rename from docs/source/api/apollon.signal.spectral.rst
rename to docs/source/generated/api/apollon.signal.spectral.rst
diff --git a/docs/source/api/apollon.signal.tools.rst b/docs/source/generated/api/apollon.signal.tools.rst
similarity index 100%
rename from docs/source/api/apollon.signal.tools.rst
rename to docs/source/generated/api/apollon.signal.tools.rst
diff --git a/docs/source/api/apollon.som.datasets.rst b/docs/source/generated/api/apollon.som.datasets.rst
similarity index 100%
rename from docs/source/api/apollon.som.datasets.rst
rename to docs/source/generated/api/apollon.som.datasets.rst
diff --git a/docs/source/api/apollon.som.defaults.rst b/docs/source/generated/api/apollon.som.defaults.rst
similarity index 100%
rename from docs/source/api/apollon.som.defaults.rst
rename to docs/source/generated/api/apollon.som.defaults.rst
diff --git a/docs/source/api/apollon.som.neighbors.rst b/docs/source/generated/api/apollon.som.neighbors.rst
similarity index 100%
rename from docs/source/api/apollon.som.neighbors.rst
rename to docs/source/generated/api/apollon.som.neighbors.rst
diff --git a/docs/source/api/apollon.som.plot.rst b/docs/source/generated/api/apollon.som.plot.rst
similarity index 100%
rename from docs/source/api/apollon.som.plot.rst
rename to docs/source/generated/api/apollon.som.plot.rst
diff --git a/docs/source/api/apollon.som.rst b/docs/source/generated/api/apollon.som.rst
similarity index 100%
rename from docs/source/api/apollon.som.rst
rename to docs/source/generated/api/apollon.som.rst
diff --git a/docs/source/api/apollon.som.som.rst b/docs/source/generated/api/apollon.som.som.rst
similarity index 100%
rename from docs/source/api/apollon.som.som.rst
rename to docs/source/generated/api/apollon.som.som.rst
diff --git a/docs/source/api/apollon.som.topologies.rst b/docs/source/generated/api/apollon.som.topologies.rst
similarity index 100%
rename from docs/source/api/apollon.som.topologies.rst
rename to docs/source/generated/api/apollon.som.topologies.rst
diff --git a/docs/source/api/apollon.som.utilities.rst b/docs/source/generated/api/apollon.som.utilities.rst
similarity index 100%
rename from docs/source/api/apollon.som.utilities.rst
rename to docs/source/generated/api/apollon.som.utilities.rst
diff --git a/docs/source/api/apollon.tools.rst b/docs/source/generated/api/apollon.tools.rst
similarity index 100%
rename from docs/source/api/apollon.tools.rst
rename to docs/source/generated/api/apollon.tools.rst
diff --git a/docs/source/api/apollon.types.rst b/docs/source/generated/api/apollon.types.rst
similarity index 100%
rename from docs/source/api/apollon.types.rst
rename to docs/source/generated/api/apollon.types.rst
diff --git a/docs/source/api/modules.rst b/docs/source/generated/api/modules.rst
similarity index 100%
rename from docs/source/api/modules.rst
rename to docs/source/generated/api/modules.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 9a0cc7c..8a19220 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -5,9 +5,9 @@
 
 Welcome to the documentation of the apollon feature extraction framework!
 =========================================================================
-*apollon* is a feature extraction and modelling frame work for music data
+*apollon* is a feature extraction and modeling framework for music data
 analysis. It handles low-level audio feature extraction, their aggreagation
-using Hidden Markov models, and comparison by means of the Self-Organizing Map.
+using Hidden Markov models, and comparison by means of the self-organizing map.
 See the :doc:`framework` chapter for gentle introduction to the mentioned
 concepts.
 
@@ -20,7 +20,7 @@ Contents
    download
    install
    framework
-   api/modules
+   generated/api/modules
 
 * :ref:`genindex`
 * :ref:`modindex`
diff --git a/docs/source/install.rst b/docs/source/install.rst
index fce46e4..a3e9a5b 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -2,8 +2,8 @@ Installation
 ***************************************
 apollon can be installed on GNU/Linux, macOS, and Windows. Installation process
 is similar on each of these plaforms. Note, however, that apollon contains
-Python C extension modules, which have to be compile locally for GNU/Linux and
-Windows users. If work on any of those platforms, please make shure that there
+CPython extension modules, which have to be compiled locally for GNU/Linux and
+Windows users. If you work on those platforms, please make shure that there
 is a C compiler set up on your machine; otherwise the installation will fail.
 In the case of macOS, a precompiled wheel is provided for the latest version
 only.
@@ -11,8 +11,8 @@ only.
 
 Install using pip
 =======================================
-The Python packager manager can automatically install download and install
-apollon from pip. Simply run the following command from your terminal:
+The Python packager manager can automatically download and install
+apollon from Pypi. Simply run the following command from your terminal:
 
 .. code-block:: Bash
 
diff --git a/src/apollon/__init__.py b/src/apollon/__init__.py
index f77bfd5..e98db76 100644
--- a/src/apollon/__init__.py
+++ b/src/apollon/__init__.py
@@ -3,7 +3,7 @@
 # mblass@posteo.net
 
 """
-apollon/__init__.py -- Main package initialization.
+Apollon feature extraction framework.
 """
 
 import os as _os
diff --git a/src/apollon/signal/__init__.py b/src/apollon/signal/__init__.py
index e69de29..0b69af2 100644
--- a/src/apollon/signal/__init__.py
+++ b/src/apollon/signal/__init__.py
@@ -0,0 +1,15 @@
+"""
+========================================
+Signal processing tools
+========================================
+
+Audio features
+========================================
+
+.. currentmodule:: apollon.signal.features
+
+.. autosummary::
+
+    cdim
+    spectral_centroid
+"""
-- 
GitLab