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