Starting to get docs skeleton in place

JohnVinyard · Sep 2, 2017 · 9aeabe4 · 9aeabe4
1 parent 7523dc4
commit 9aeabe4
Show file tree

Hide file tree

Showing 11 changed files with 112 additions and 12 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -293,6 +293,12 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
 
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/', None),
+    'numpy': ('http://docs.scipy.org/doc/numpy/', None),
+}
+
 # Fake imports
 import mock
 
@@ -303,6 +309,9 @@
     'numpy.lib',
     'numpy.lib.stride_tricks',
     'numpy.ma',
+    'numpy.core',
+    'numpy.core.multiarray',
+    'numpy.random',
 
     'scipy',
     'scipy.signal',
@@ -321,6 +330,10 @@
 
 
 class ZoundsDocsMock(mock.Mock):
+    __version__ = 1.0
+
+    ndarray = object
+
     def __init__(self, *args, **kwargs):
         super(ZoundsDocsMock, self).__init__(side_effect=None)
 

diff --git a/docs/source/core.rst b/docs/source/core.rst
@@ -1,4 +1,22 @@
+Core
+====
 .. automodule:: zounds.core
+.. currentmodule:: zounds.core
+
+Numpy Arrays with Semantically Meaningful Indexing
+--------------------------------------------------
+.. autoclass:: ArrayWithUnits
+    :members:
+
+Custom Dimensions
+-----------------
+.. autoclass:: Dimension
+    :members:
+
+.. autoclass:: IdentityDimension
+    :members:
+
+
 
 
 
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,15 +6,19 @@
 Welcome to zounds' documentation!
 ==================================
 
+Zounds is a python library to make working with sound easy.
+
+
 
 API documentation
 -----------------
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
-    core
+    timeseries
     spectral
+    core
 
 Indices and tables
 ------------------

diff --git a/docs/source/spectral.rst b/docs/source/spectral.rst
@@ -5,10 +5,11 @@ Spectral
 
 Representations
 ---------------
-Something here
+.. autoclass:: FrequencyDimension
+    :members:
 
 Nodes
-----------------
+-----
 Something there
 
 Scales

diff --git a/docs/source/timeseries.rst b/docs/source/timeseries.rst
@@ -0,0 +1,20 @@
+Timeseries
+==========
+.. automodule:: zounds.timeseries
+.. currentmodule:: zounds.timeseries
+
+The Time Dimension
+------------------
+.. autoclass:: TimeDimension
+    :members:
+
+Durations and Sample Rates
+--------------------------
+
+Audio Samples
+-------------
+.. autoclass:: AudioSamples
+    :members:
+
+Variable Rate Time Series
+-------------------------
diff --git a/zounds/core/__init__.py b/zounds/core/__init__.py
@@ -1,10 +1,8 @@
 """
-Core
-====
-
-Here is some text about core.
-
-.. autoclass:: ArrayWithUnits
+The core module introduces the key building blocks of the representations zounds
+deals in: :class:`ArrayWithUnits`, a :class:`numpy.ndarray`-derived class that
+supports semantically meaningful indexing, and :class:`Dimension`, a common
+base class for custom, user-defined dimensions.
 """
 
 from dimensions import Dimension, IdentityDimension

diff --git a/zounds/core/axis.py b/zounds/core/axis.py
@@ -12,7 +12,20 @@ def __init__(self):
 
 class ArrayWithUnits(np.ndarray):
     """
-    Here is documentation for ArrayWithUnits
+    Blah Blah Blah
+
+    Args:
+        arr (ndarray): The :class:`numpy.ndarray` instance containing the raw
+                       data for this instance
+        dimensions (iterable): iterable of :class:`Dimension`-derived classes
+
+    Examples:
+        >>> print 'hai'
+
+    See Also:
+        :class:`IdentityDimension`
+        :class:`zounds.timeseries.TimeDimension`
+        :class:`zounds.spectral.FrequencyDimension`
     """
 
     def __new__(cls, arr, dimensions):
@@ -70,6 +83,10 @@ def concat(cls, arrs, axis=0):
 
     @classmethod
     def from_example(cls, data, example):
+        """
+        Produce a new :class:`ArrayWithUnits` instance given some raw data and
+        an example instance that has the desired dimensions
+        """
         return ArrayWithUnits(data, example.dimensions)
 
     @classmethod

diff --git a/zounds/core/dimensions.py b/zounds/core/dimensions.py
@@ -14,6 +14,13 @@ def metaslice(self, index, size):
         return self
 
     def integer_based_slice(self, index):
+        """
+        Transforms a custom, user-defined slice into integer indices that numpy
+        can understand
+
+        Args:
+            index (custom slice): A user-defined slice instance
+        """
         raise NotImplementedError()
 
     def validate(self, size):

diff --git a/zounds/spectral/sliding_window.py b/zounds/spectral/sliding_window.py
@@ -1,5 +1,4 @@
 import numpy as np
-import scipy
 from featureflow import Node, NotEnoughData
 
 from zounds.core import ArrayWithUnits

diff --git a/zounds/timeseries/__init__.py b/zounds/timeseries/__init__.py
@@ -1,3 +1,8 @@
+"""
+The timeseries module introduces classes for dealing with time as it relates
+to audio signals
+"""
+
 from duration import \
     Hours, Minutes, Seconds, Milliseconds, Microseconds, Picoseconds
 

diff --git a/zounds/timeseries/audiosamples.py b/zounds/timeseries/audiosamples.py
@@ -8,6 +8,24 @@
 
 
 class AudioSamples(ArrayWithUnits):
+    """
+    Represents audio samples
+
+    Args:
+        array (np.ndarray): The raw sample data
+        samplerate (SampleRate): The rate at which data was sampled
+
+    Examples::
+        >>> import zounds
+        >>> import numpy as np
+        >>> raw = np.random.normal(0, 1, 44100)
+        >>> samples = zounds.AudioSamples(raw, zounds.SR44100())
+        >>> samples.samples_per_second
+        44100
+        >>> samples.channels
+        1
+    """
+
     def __new__(cls, array, samplerate):
         if array.ndim == 1:
             dimensions = [TimeDimension(*samplerate)]