DOC: Major documentation update

Author: mgeier

README.rst

@@ -17,25 +17,29 @@ Features:
 
 * playback of multiple signals at the same time (that's why it's called "mixer")
 
-* non-blocking callback function, using PortAudio ringbuffers
-
 * play from buffer, play from ringbuffer
 
 * record into buffer, record into ringbuffer
 
 * multichannel support
 
-* all memory allocations/deallocations happen outside of the audio callback
-
-* NumPy arrays with data type 'float32' can be easily used (via the buffer
+* NumPy arrays with data type ``'float32'`` can be easily used (via the buffer
   protocol) as long as they are C-contiguous
 
-Planned features:
+* fixed latency playback, (close to) no jitter (optional)
 
-* fixed latency playback, no jitter (optional)
+  * to be verified ...
 
 * sample-accurate playback/recording (with known offset)
 
+  * to be verified ...
+
+* non-blocking callback function, using PortAudio ringbuffers
+
+* all memory allocations/deallocations happen outside the audio callback
+
+Planned features:
+
 * meticulous reporting of overruns/underruns
 
 * loopback tests to verify correct operation and accurate latency values

doc/conf.py

@@ -1,36 +1,18 @@
 from subprocess import check_output
 
-needs_sphinx = '1.3'  # for sphinx.ext.napoleon
-
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
-    'sphinx.ext.napoleon',  # support for NumPy-style docstrings
 ]
 
-autoclass_content = 'init'
-autodoc_member_order = 'bysource'
-
-napoleon_google_docstring = False
-napoleon_numpy_docstring = True
-napoleon_include_private_with_doc = False
-napoleon_include_special_with_doc = False
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_param = False
-napoleon_use_rtype = False
-
 intersphinx_mapping = {
     'python': ('https://docs.python.org/3/', None),
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
-    'sounddevice': ('http://python-sounddevice.readthedocs.io/en/latest/',
-                    None),
+    'sounddevice':
+        ('http://python-sounddevice.readthedocs.io/en/latest/', None),
 }
 
-source_suffix = '.rst'
 master_doc = 'index'
 
 authors = 'Matthias Geier'

doc/index.rst

@@ -8,9 +8,22 @@ API Documentation
 -----------------
 
 .. automodule:: rtmixer
+
+.. autoclass:: Mixer
+   :members: play_buffer, play_ringbuffer, actions, cancel, wait
+   :undoc-members:
+
+.. autoclass:: Recorder
    :members:
    :undoc-members:
 
+.. autoclass:: MixerAndRecorder
+   :members:
+   :undoc-members:
+
+.. autoclass:: RingBuffer
+   :inherited-members:
+
 .. only:: html
 
    Index

setup.py

@@ -29,7 +29,7 @@
     long_description=open('README.rst').read(),
     license='MIT',
     keywords='sound audio PortAudio realtime low-latency'.split(),
-    #url='http://python-rtmixer.readthedocs.io/',
+    url='http://python-rtmixer.readthedocs.io/',
     platforms='any',
     classifiers=[
         'License :: OSI Approved :: MIT License',

src/rtmixer.py

@@ -1,5 +1,8 @@
-"""Reliable low-latency audio playback and recording."""
+"""Reliable low-latency audio playback and recording.
 
+http://python-rtmixer.readthedocs.io/
+
+"""
 __version__ = '0.0.0'
 
 import sounddevice as _sd
@@ -45,7 +48,8 @@ def cancel(self, action, time=0, allow_belated=True):
         order to stop the given *action*.
 
         This function typically returns before the *action* is actually
-        stopped.  Use `wait()` to wait until it's done.
+        stopped.  Use `wait()` (on either one of the two actions) to
+        wait until it's done.
 
         """
         cancel_action = _ffi.new('struct action*', dict(
@@ -99,17 +103,22 @@ def _drain_result_q(self):
 
 
 class Mixer(_Base):
-    """PortAudio output stream for realtime mixing."""
+    """PortAudio output stream for realtime mixing.
 
-    def __init__(self, **kwargs):
-        """Create a realtime mixer object.
+    Takes the same keyword arguments as `sounddevice.OutputStream`,
+    except *callback* (a callback function implemented in C is used
+    internally) and *dtype* (which is always ``'float32'``).
 
-        Takes the same keyword arguments as `sounddevice.OutputStream`,
-        except *callback* and *dtype*.
+    Uses default values from `sounddevice.default` (except *dtype*,
+    which is always ``'float32'``).
 
-        Uses default values from `sounddevice.default`.
+    Has the same methods and attributes as `sounddevice.OutputStream`
+    (except :meth:`~sounddevice.Stream.write` and
+    :attr:`~sounddevice.Stream.write_available`), plus the following:
 
-        """
+    """
+
+    def __init__(self, **kwargs):
         _Base.__init__(self, kind='output', **kwargs)
         self._state.output_channels = self.channels
 
@@ -136,10 +145,10 @@ def play_buffer(self, buffer, channels, start=0, allow_belated=True):
 
     def play_ringbuffer(self, ringbuffer, channels=None, start=0,
                         allow_belated=True):
-        """Send a ring buffer to the callback to be played back.
+        """Send a `RingBuffer` to the callback to be played back.
 
         By default, the number of channels is obtained from the ring
-        buffer's *elementsize*.
+        buffer's :attr:`~RingBuffer.elementsize`.
 
         """
         _, samplesize = _sd._split(self.samplesize)
@@ -162,17 +171,21 @@ def play_ringbuffer(self, ringbuffer, channels=None, start=0,
 
 
 class Recorder(_Base):
-    """PortAudio input stream for realtime recording."""
+    """PortAudio input stream for realtime recording.
 
-    def __init__(self, **kwargs):
-        """Create a realtime recording object.
+    Takes the same keyword arguments as `sounddevice.InputStream`,
+    except *callback* (a callback function implemented in C is used
+    internally) and *dtype* (which is always ``'float32'``).
 
-        Takes the same keyword arguments as `sounddevice.InputStream`,
-        except *callback* and *dtype*.
+    Uses default values from `sounddevice.default` (except *dtype*,
+    which is always ``'float32'``).
 
-        Uses default values from `sounddevice.default`.
+    Has the same methods and attributes as `Mixer`, except that
+    `play_buffer()` and `play_ringbuffer()` are replaced by:
 
-        """
+    """
+
+    def __init__(self, **kwargs):
         _Base.__init__(self, kind='input', **kwargs)
         self._state.input_channels = self.channels
 
@@ -197,10 +210,10 @@ def record_buffer(self, buffer, channels, start=0, allow_belated=True):
 
     def record_ringbuffer(self, ringbuffer, channels=None, start=0,
                           allow_belated=True):
-        """Send a ring buffer to the callback to be recorded into.
+        """Send a `RingBuffer` to the callback to be recorded into.
 
         By default, the number of channels is obtained from the ring
-        buffer's *elementsize*.
+        buffer's :attr:`~RingBuffer.elementsize`.
 
         """
         samplesize, _ = _sd._split(self.samplesize)
@@ -223,17 +236,20 @@ def record_ringbuffer(self, ringbuffer, channels=None, start=0,
 
 
 class MixerAndRecorder(Mixer, Recorder):
-    """PortAudio stream for realtime mixing and recording."""
+    """PortAudio stream for realtime mixing and recording.
 
-    def __init__(self, **kwargs):
-        """Create a realtime mixer object with recording capabilities.
+    Takes the same keyword arguments as `sounddevice.Stream`, except
+    *callback* (a callback function implemented in C is used internally)
+    and *dtype* (which is always ``'float32'``).
 
-        Takes the same keyword arguments as `sounddevice.Stream`,
-        except *callback* and *dtype*.
+    Uses default values from `sounddevice.default` (except *dtype*,
+    which is always ``'float32'``).
 
-        Uses default values from `sounddevice.default`.
+    Inherits all methods and attributes from `Mixer` and `Recorder`.
 
-        """
+    """
+
+    def __init__(self, **kwargs):
         _Base.__init__(self, kind='duplex', **kwargs)
         self._state.input_channels = self.channels[0]
         self._state.output_channels = self.channels[1]