Merge pull request #30 from interactive-sonification/develop

Release 0.3.2

.coveragerc

@@ -1,2 +1,10 @@
 [run]
 source = pya
+
+[report]
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain if tests don't hit defensive assertion code:
+    raise NotImplementedError

.travis.yml

@@ -18,7 +18,7 @@ install:
   - conda create -q -n test-environment python=$TRAVIS_PYTHON_VERSION ffmpeg coverage python-coveralls --file=requirements.txt --file=requirements_test.txt
   - source activate test-environment
 
-script: nosetests --with-coverage --cover-package=pya
+script: pytest --cov pya/
 after_success:
   - coveralls --config_file .coveragerc
 

Changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.3.2 (November 2019)
+
+* Create gh-pages branch and Documentation website
+* Update README info
+* New Arecorder method to individualize channel selection and gain adjustment to each channel
+* Webaudio backend
+* binder example based on webaudio backend
+* Update docstrings
+* Fix bug of multi channel fade_in fade_out
+* Allowing using timeslice in extend setitem mode as long as stop reaches the end of the array.
+* Add Jupyter backend
+* Configure Binder for easier testing
+* Switch test framework from nosetests to pytest
+
 ## 0.3.1 (October 2019)
 
 * Remove ffmpeg from requirement, and it has to be installed via conda or manually

MANIFEST.in

@@ -6,12 +6,23 @@ include .pylintrc
 include LICENSE
 include MANIFEST
 include tox.ini
+include binder/environment.yml
+include binder/postBuild
 
+recursive-include docs Makefile
+recursive-include docs *.bat
+recursive-include docs *.html
+recursive-include docs *.py
+recursive-include docs *.rst
+
+recursive-include examples *.aif
 recursive-include examples *.ipynb
+recursive-include examples *.mp3
 recursive-include examples *.py
 recursive-include examples *.wav
-recursive-include examples *.mp3
-recursive-include examples *.aif
+recursive-exclude examples .ipynb_checkpoints/*.ipynb
+
 recursive-include tests *.py
-recursive-exclude examples/.ipynb_checkpoints *.ipynb
 recursive-include pya *.py
+recursive-include dev *.md
+recursive-include dev *.py 

README.md

@@ -1,24 +1,21 @@
-[![Version](https://img.shields.io/badge/version-v0.3.1-orange.svg)](https://github.com/interactive-sonification/pya)
 [![PyPI](https://img.shields.io/pypi/v/pya.svg)](https://pypi.org/project/pya)
-[![GitHub commits](https://img.shields.io/github/commits-since/interactive-sonification/pya/v0.3.0.svg)](https://github.com/interactive-sonification/pya/compare/v0.3.0...master)
 [![License](https://img.shields.io/github/license/interactive-sonification/pya.svg)](LICENSE)
-[![Build Status Travis](https://travis-ci.org/interactive-sonification/pya.svg?branch=develop)](https://travis-ci.org/interactive-sonification/pya)
-[![Build status AppVeyor](https://ci.appveyor.com/api/projects/status/vn61qeri0uyxeedv/branch/develop?svg=true)](https://ci.appveyor.com/project/aleneum/pya-b7gkx/branch/develop)
-<!--
-[![Coverage Status](https://coveralls.io/repos/interactive-sonification/pya/badge.svg?branch=master&service=github)](https://coveralls.io/github/interactive-sonification/pya?branch=master)
--->
 
-<!--[![Name](Image)](Link)-->
+# pya
 
-# pyA
+|Branch|`master`|`develop`|
+|------:|--------:|---------:|
+|[CI-Linux/MacOS](https://travis-ci.org/interactive-sonification/pya) | ![Build Status Travis](https://travis-ci.org/interactive-sonification/pya.svg?branch=master) | ![Build Status Travis](https://travis-ci.org/interactive-sonification/pya.svg?branch=develop) |
+|[CI-Windows](https://ci.appveyor.com/project/aleneum/pya-b7gkx/)| ![Build status AppVeyor](https://ci.appveyor.com/api/projects/status/vn61qeri0uyxeedv/branch/master?svg=true) | ![Build status AppVeyor](https://ci.appveyor.com/api/projects/status/vn61qeri0uyxeedv/branch/develop?svg=true) | 
+|Changes|[![GitHub commits](https://img.shields.io/github/commits-since/interactive-sonification/pya/v0.3.1/master.svg)](https://github.com/interactive-sonification/pya/compare/v0.3.1...master) | [![GitHub commits](https://img.shields.io/github/commits-since/interactive-sonification/pya/v0.3.1/develop.svg)](https://github.com/interactive-sonification/pya/compare/v0.3.1...develop) |
+|Binder|[![Master Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/interactive-sonification/pya/master?filepath=examples%2Fpya-examples.ipynb) | [![Develop Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/interactive-sonification/pya/develop?filepath=examples%2Fpya-examples.ipynb) |
 
-## What is pyA?
+## What is pya?
 
-pyA is a package to support creation and manipulation of audio signals with Python.
+pya is a package to support creation and manipulation of audio signals with Python.
 It uses numpy arrays to store and compute audio signals.
 
-  * Website: --
-  * Documentation: see examples/pya-examples.ipynb and help(pya)
+  * Documentation: see examples/pya-examples.ipynb for a quick tutorial and [Documentation](https://interactive-sonification.github.io/pya/index.html)
   * Source code: https://github.com/interactive-sonification/pya
 
 It provides:
@@ -30,14 +27,16 @@ It provides:
   * Arecorder - an audio recorder class
   * Aspec - an audio spectrum class, using rfft as real-valued signals are always implied
   * Astft - an audio STFT (short-term Fourier transform) class
+  * A number of helper functions, e.g. device_info()
 
-pyA can be used for
+pya can be used for
 * multi-channel audio processing
 * auditory display and sonification
 * sound synthesis experiment
 * audio applications in general such as games or GUI-enhancements
 * signal analysis and plotting
-* at this time more suitable for offline rendering than realtime.
+
+At this time pya is more suitable for offline rendering than realtime.
 
 ## Authors and Contributors
 
@@ -48,16 +47,9 @@ pyA can be used for
 
 ## Installation
 
-<!-- **Disclaimer**: We are currently making sure that pyA can be uploaded to PyPI, until then clone the master branch and from inside the pya directory install via `pip install -e .` -->
-
-**Note**: pya can be installed using **pip**. But pya uses PyAudio for audio playback and record, and PyAudio 0.2.11 has yet to fully support Python 3.7. So using pip install with Python 3.7 may encounter issues such as portaudio. Solution
-
-Use pip to install pya via
-
-    pip install pya
-
-**Note**: pyA requires PyAudio, for playback and record, which in turn requires portaudio. Since PyAudio 0.2.11 has yet to fully support Python 3.7, you maybe encounter portaudio related error under Python 3.7. Lower versions of Python should be fine. A few solutions are:
+<!-- **Disclaimer**: We are currently making sure that pya can be uploaded to PyPI, until then clone the master branch and from inside the pya directory install via `pip install -e .` -->
 
+**Note**: pya can be installed using **pip**. But pya uses PyAudio for audio playback and record, and PyAudio 0.2.11 has yet to fully support Python 3.7. So using pip install with Python 3.7 may encounter issues such as portaudio. Solutions are:
 
 1. Anaconda can install non-python packages, so that the easiest way (if applicable) would be to 
 
@@ -70,7 +62,9 @@ Use pip to install pya via
 4. For Windows users, you can install PyAudio wheel at:
 https://www.lfd.uci.edu/~gohlke/pythonlibs/#pyaudio
 
+Then pya can be installed using pip:
 
+    pip install pya
 
 
 See pyaudio installation http://people.csail.mit.edu/hubert/pyaudio/#downloads

appveyor.yml

@@ -1,6 +1,6 @@
 # no dedicated build phase needed so far
 build: false
-version: "0.3.1-{build}"
+version: "0.3.2-{build}"
 
 branches:
   only:
@@ -26,4 +26,4 @@ install:
   - activate test-environment
 
 test_script:
-  - nosetests --with-coverage --cover-package=pya
+  - pytest

binder/environment.yml

@@ -0,0 +1,11 @@
+name: pya
+dependencies:
+- numpy
+- scipy
+- matplotlib
+- pyaudio>=0.2.11
+- ffmpeg
+- ipywidgets
+- requests
+- notebook
+- sanic

binder/postBuild

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+export JUPYTER_SERVER_URL
+pip install jupyter_server_proxy
+jupyter serverextension enable --py jupyter_server_proxy --sys-prefix

dev/generate_doc.py

@@ -0,0 +1,44 @@
+import argparse
+import sys
+import os 
+import subprocess
+from os.path import exists
+
+TEMP_FOLDER = 'build/git'
+BUILD_FOLDER = f'{TEMP_FOLDER}/build/html'
+VERSION_FILE = "versions.html"
+
+
+def generate(args):
+    out = subprocess.check_output("git show-ref --tags -d".split(' '))
+    tags = [str(line.split(b' ')[1].split(b'/')[2], 'utf-8') for line in out.split(b'\n')[:-1]]
+    branches = ['develop', 'master']
+    generated = []
+    if not exists(TEMP_FOLDER):
+        os.system(f'git clone https://github.com/interactive-sonification/pya.git {TEMP_FOLDER}')
+        os.makedirs(BUILD_FOLDER)
+    # first, check which documentation to generate
+    for t in branches + tags[::-1]:
+        if t not in branches:
+            t = 'tags/' + t
+        os.system(f'git -C {TEMP_FOLDER} checkout {t}')
+        if exists(f'{TEMP_FOLDER}/docs/'):
+            generated.append(t)
+        else:
+            print(f'{t} has no docs!')
+    # generate documentation; all versions have to be known for the dropdown menu
+    for t in generated:
+        os.system(f'git -C {TEMP_FOLDER} checkout {t}')
+        os.system(f'sphinx-build -b html -D version={t} -A versions={",".join(generated)} {TEMP_FOLDER}/docs {BUILD_FOLDER}/{t}')
+    # create index html to forward to last tagged version
+    default_version = generated[len(branches)] if len(generated) > len(branches) else generated[-1]
+    with open(f'{BUILD_FOLDER}/index.html', 'w') as fp:
+        fp.write(f"""<!DOCTYPE html>
+        <html><head>
+        <meta http-equiv="refresh" content="0; url={default_version}/index.html">
+        </head></html>
+        """)
+
+
+if __name__ == "__main__":
+    generate(sys.argv[1:])

docs/Makefile

@@ -0,0 +1,29 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = ../../pyadoc-test-docs
+# PDFBUILDDIR   = /tmp
+# PDF           = ../manual.pdf
+
+# latexpdf:
+#     $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(PDFBUILDDIR)/latex
+#     @echo "Running LaTeX files through pdflatex..."
+#     make -C $(PDFBUILDDIR)/latex all-pdf
+# 	cp $(PDFBUILDDIR)/latex/*.pdf $(PDF)
+#     @echo "pdflatex finished; see $(PDF)"
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# 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)

docs/_templates/layout.html

@@ -0,0 +1,39 @@
+{% extends "!layout.html" %}
+{% block sidebartitle %}
+
+{% if logo and theme_logo_only %}
+<a href="{{ pathto(master_doc) }}">
+{% else %}
+<a href="{{ pathto(master_doc) }}" class="icon icon-home" alt="{{ _("Documentation Home") }}"> {{ project }}
+{% endif %}
+
+{% if logo %}
+{# Not strictly valid HTML, but it's the only way to display/scale
+    it properly, without weird scripting or heaps of work
+#}
+<img src="{{ pathto('_static/' + logo, 1) }}" class="logo" alt="{{ _('Logo') }}"/>
+{% endif %}
+</a>
+
+{% if theme_display_version %}
+{%- set nav_version = version %}
+{% if READTHEDOCS and current_version %}
+    {%- set nav_version = current_version %}
+{% endif %}
+{% if nav_version %}
+
+<div class="version">
+version: <select style="padding: 0;" onchange="location = this.value;" autocomplete="off">
+{% for ver in versions.split(',') %}
+  <option value="/{{ver}}/" {% if ver == version %}selected="selected"{% endif %}>{{ver}}</option>
+{% endfor %}
+<select>
+</div>
+
+
+{% endif %}
+{% endif %}
+
+{% include "searchbox.html" %}
+
+{% endblock %}

docs/conf.py

@@ -0,0 +1,59 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# 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('..'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'pya'
+copyright = '2019, Thomas Hermann, Jiajun Yang, Alexander Neumann'
+author = 'Thomas Hermann, Jiajun Yang, Alexander Neumann'
+
+# The full version, including alpha/beta/rc tags
+version = '0.3.2'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx.ext.autodoc', 
+              'sphinx.ext.napoleon',
+              'm2r']
+
+
+source_suffix = ['.rst', '.md']
+
+# 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 = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []

docs/includeme.rst

@@ -0,0 +1,2 @@
+
+.. mdinclude:: ../README.md

docs/index.rst

@@ -0,0 +1,22 @@
+pya
+===
+
+pya is a package to support creation and manipulation of audio signals 
+with Python. Project can be found on `Github
+<https://github.com/interactive-sonification/pya>`_.
+For bug reports and other technical issues, please use the `Github Issues
+<https://github.com/interactive-sonification/pya/issues>`_.
+
+.. toctree::
+   :maxdepth: 2
+
+   includeme
+   modules
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`