Merge pull request #72 from marl/auroracramer/fixdocs

Fix API documentation and build

README.md

@@ -4,8 +4,8 @@ OpenL3 is an open-source Python library for computing deep audio and image embed
 
 [![PyPI](https://img.shields.io/badge/python-2.7%2C%203.5%2C%203.6-blue.svg)](https://pypi.python.org/pypi/openl3)
 [![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://choosealicense.com/licenses/mit/)
-[![Build Status](https://travis-ci.org/marl/openl3.svg?branch=master)](https://travis-ci.org/marl/openl3)
-[![Coverage Status](https://coveralls.io/repos/github/marl/openl3/badge.svg?branch=master)](https://coveralls.io/github/marl/openl3?branch=master)
+[![Build Status](https://travis-ci.com/marl/openl3.svg?branch=main)](https://travis-ci.com/marl/openl3)
+[![Coverage Status](https://coveralls.io/repos/github/marl/openl3/badge.svg?branch=main)](https://coveralls.io/github/marl/openl3?branch=main)
 [![Documentation Status](https://readthedocs.org/projects/openl3/badge/?version=latest)](http://openl3.readthedocs.io/en/latest/?badge=latest)
 
 Please refer to the [documentation](https://openl3.readthedocs.io/en/latest/) for detailed instructions and examples.
@@ -69,11 +69,11 @@ if needed. To install OpenL3 using ``pip``, simply run
 
 To install the latest version of OpenL3 from source:
 
-1. Clone or pull the lastest version:
+1. Clone or pull the latest version, only retrieving the ``main`` branch to avoid downloading the branch where we store the model weight files (these will be properly downloaded during installation).
 
-        git clone [email protected]:marl/openl3.git
+        git clone [email protected]:marl/openl3.git --branch main --single-branch
 
-2. Install using pip to handle python dependencies:
+2. Install using pip to handle python dependencies. The installation also downloads model files, **which requires a stable network connection**.
 
         cd openl3
         pip install -e .

docs/changes.rst

@@ -3,6 +3,19 @@
 Changelog
 ---------
 
+v0.4.2
+~~~~~~
+ - Fix incorrect embedding_size in ``load_image_embedding_model`` docstring
+ - Add ``tensorflow.keras`` mock modules to ``docs/conf.py`` to fix docs build
+ - Remove pin on ``sphinx`` version
+
+v0.4.1
+~~~~~~
+ - Add librosa as an explicit dependency
+ - Remove upper limit pinning for scikit-image dependency
+ - Fix version number typo in README
+ - Update TensorFlow information in README
+
 v0.4.0
 ~~~~~~
  - Upgraded to `tensorflow>=2.0.0`. Tensorflow is now included as a dependency because of dual CPU-GPU support.
@@ -22,30 +35,30 @@ v0.4.0
 
 v0.3.1
 ~~~~~~
-- Require `keras>=2.0.9,<2.3.0` in dependencies to avoid force installation of TF 2.x during pip installation.
-- Update README and installation docs to explicitly state that we do not yet support TF 2.x and to offer a working dependency combination.
-- Require `kapre==0.1.4` in dependencies to avoid installing `tensorflow>=1.14` which break regression tests.
+ - Require `keras>=2.0.9,<2.3.0` in dependencies to avoid force installation of TF 2.x during pip installation.
+ - Update README and installation docs to explicitly state that we do not yet support TF 2.x and to offer a working dependency combination.
+ - Require `kapre==0.1.4` in dependencies to avoid installing `tensorflow>=1.14` which break regression tests.
 
 
 v0.3.0
 ~~~~~~
-- Rename audio related embedding functions to indicate that they are specific to audio.
-- Add image embedding functionality to API and CLI.
-- Add video processing functionality to API and CLI.
-- Add batch processing functionality to API and CLI to more efficiently process multiple inputs.
-- Update documentation with new functionality.
-- Address build issues with updated dependencies.
+ - Rename audio related embedding functions to indicate that they are specific to audio.
+ - Add image embedding functionality to API and CLI.
+ - Add video processing functionality to API and CLI.
+ - Add batch processing functionality to API and CLI to more efficiently process multiple inputs.
+ - Update documentation with new functionality.
+ - Address build issues with updated dependencies.
 
 v0.2.0
 ~~~~~~
-- Update embedding models with ones that have been trained with the kapre bug fixed.
-- Allow loaded models to be passed in and used in `process_file` and `get_embedding`.
-- Rename `get_embedding_model` to `load_embedding_model`.
+ - Update embedding models with ones that have been trained with the kapre bug fixed.
+ - Allow loaded models to be passed in and used in `process_file` and `get_embedding`.
+ - Rename `get_embedding_model` to `load_embedding_model`.
 
 v0.1.1
 ~~~~~~
-- Update kapre to fix issue with dynamic range normalization for decibel computation when computing spectrograms.
+ - Update kapre to fix issue with dynamic range normalization for decibel computation when computing spectrograms.
 
 v0.1.0
 ~~~~~~
-- First release.
+ - First release.

docs/conf.py

@@ -27,8 +27,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'OpenL3'
-copyright = '2018, Jason Cramer, Ho-Hsiang Wu, and Justin Salamon'
-author = 'Jason Cramer, Ho-Hsiang Wu, and Justin Salamon'
+copyright = '2018-2021, Aurora Cramer, Ho-Hsiang Wu, Bea Steers, and Justin Salamon'
+author = 'Aurora Cramer, Ho-Hsiang Wu, Bea Steers, and Justin Salamon'
 
 
 # -- Mock dependencies
@@ -44,8 +44,9 @@ def getattr(cls, name):
 
 MOCK_MODULES = [
     'numpy', 'soundfile', 'resampy', 'keras', 'tensorflow',
-    'kapre', 'kapre.time_frequency', 'keras.layers', 'keras.models',
-    'keras.regularizers', 'sklearn', 'sklearn.decomposition', 'skimage',
+    'tensorflow.keras', 'tensorflow.keras.layers', 'tensorflow.keras.backend',
+    'tensorflow.keras.regularizers', 'kapre', 'kapre.time_frequency',
+    'sklearn', 'sklearn.decomposition', 'skimage',
     'moviepy', 'skimage.io', 'moviepy.video', 'moviepy.video.io',
     'moviepy.video.io.VideoFileClip'
 ]

docs/installation.rst

@@ -47,11 +47,11 @@ if needed. To install OpenL3 using ``pip``, simply run
 
 To install the latest version of OpenL3 from source:
 
-1. Clone or pull the lastest version:
+1. Clone or pull the latest version, only retrieving the ``main`` branch to avoid downloading the branch where we store the model weight files (these will be properly downloaded during installation).
 
->>> git clone git@github.com:marl/openl3.git
+>>> git clone git@github.com:marl/openl3.git --branch main --single-branch
 
-2. Install using pip to handle python dependencies:
+2. Install using pip to handle python dependencies. The installation also downloads model files, which requires a stable network connection.
 
 >>> cd openl3
 >>> pip install -e .

openl3/models.py

@@ -19,7 +19,8 @@
 VALID_FRONTENDS = ("librosa", "kapre")
 VALID_INPUT_REPRS = ("linear", "mel128", "mel256")
 VALID_CONTENT_TYPES = ("music", "env")
-VALID_EMBEDDING_SIZES = (6144, 512)
+VALID_AUDIO_EMBEDDING_SIZES = (6144, 512)
+VALID_IMAGE_EMBEDDING_SIZES = (8192, 512)
 
 
 def _log10(x):
@@ -179,7 +180,7 @@ def load_image_embedding_model(input_repr, content_type, embedding_size):
         Spectrogram representation used for audio model.
     content_type : "music" or "env"
         Type of content used to train embedding.
-    embedding_size : 6144 or 512
+    embedding_size : 8192 or 512
         Embedding dimensionality.
 
     Returns

openl3/version.py

@@ -1,2 +1,2 @@
 short_version = '0.4'
-version = '0.4.0rc2'
+version = '0.4.2-dev'

setup.py

@@ -50,8 +50,8 @@
     long_description=long_description,
     long_description_content_type='text/markdown',
     url='https://github.com/marl/openl3',
-    author='Jason Cramer, Ho-Hsiang Wu, Bea Steers, and Justin Salamon',
-    author_email='jtcramer@nyu.edu',
+    author='Aurora Cramer, Ho-Hsiang Wu, Bea Steers, and Justin Salamon',
+    author_email='jtc440@nyu.edu',
     packages=find_packages(),
     entry_points={
         'console_scripts': ['openl3=openl3.cli:main'],
@@ -88,7 +88,7 @@
     ],
     extras_require={
         'docs': [
-                'sphinx==1.2.3',  # autodoc was broken in 1.3.1
+                'sphinx',
                 'sphinxcontrib-napoleon',
                 'sphinx_rtd_theme',
                 'numpydoc',