DOC: Split documentation into several pages

Author: mgeier

README.rst

@@ -13,260 +13,6 @@ Source code repository and issue tracker:
 License:
    MIT -- see the file ``LICENSE`` for details.
 
-Installation
-------------
-
-First of all, you'll need Python_.
-Any version where CFFI_ is supported should work.
-If you don't have Python installed yet, you should get one of the
-distributions which already include CFFI and NumPy_ (and many other useful
-things), e.g. Anaconda_ or WinPython_.
-
-.. image:: https://anaconda.org/conda-forge/python-sounddevice/badges/version.svg
-   :target: https://anaconda.org/conda-forge/python-sounddevice
-
-If you are using the ``conda`` package manager (e.g. with Anaconda_ for
-Linux/macOS/Windows), you can install the ``sounddevice`` module from the
-``conda-forge`` channel::
-
-   conda install -c conda-forge python-sounddevice
-
-There are also packages for several other package managers:
-
-.. image:: https://repology.org/badge/vertical-allrepos/python:sounddevice.svg
-   :target: https://repology.org/metapackage/python:sounddevice
-
-If you are using Windows, you can alternatively install one of the packages
-provided at https://www.lfd.uci.edu/~gohlke/pythonlibs/#sounddevice.
-The PortAudio library is included in the package and you can get the rest
-of the dependencies on the same page.
-
-Note that some of the aforementioned packages may be out-of-date.
-You can always get the newest ``sounddevice`` release from PyPI_
-(using ``pip``).
-If you want to try the latest development version, have a look at the section
-about `Contributing`_.
-
-.. image:: https://badge.fury.io/py/sounddevice.svg
-   :target: https://pypi.org/project/sounddevice/
-
-To install the latest release from PyPI, use::
-
-   python3 -m pip install sounddevice --user
-
-If you want to install it system-wide for all users (assuming you have the
-necessary rights), you can just drop the ``--user`` option.
-If you have installed the module already, you can use the ``--upgrade`` flag to
-get the newest release.
-
-To un-install, use::
-
-   python3 -m pip uninstall sounddevice
-
-If you install the ``sounddevice`` module with ``pip`` on macOS or Windows, the
-PortAudio_ library will be installed automagically.
-On other platforms, you might have to install PortAudio with your package
-manager (the package might be called ``libportaudio2`` or similar).
-
-You might also have to install CFFI_ (from a package called ``python3-cffi`` or
-similar).
-
-NumPy_ is only needed if you want to play back and record NumPy arrays.
-The classes `sounddevice.RawStream`, `sounddevice.RawInputStream` and
-`sounddevice.RawOutputStream` use plain Python buffer objects and don't need
-NumPy at all.
-If you need NumPy, you should install it with your package manager (from a
-package named ``python3-numpy`` or similar) or use a Python distribution that
-already includes NumPy (see above).
-You can also install NumPy with ``pip``, but depending on your platform, this
-might require a compiler and several additional libraries.
-
+.. _Python: https://www.python.org/
 .. _PortAudio: http://www.portaudio.com/
 .. _NumPy: http://www.numpy.org/
-.. _Python: https://www.python.org/
-.. _Anaconda: https://www.anaconda.com/download/
-.. _WinPython: http://winpython.github.io/
-.. _CFFI: http://cffi.readthedocs.io/
-.. _PyPI: https://pypi.org/project/sounddevice/
-
-Usage
------
-
-First, import the module:
-
-.. code:: python
-
-   import sounddevice as sd
-
-Playback
-^^^^^^^^
-
-Assuming you have a NumPy array named ``myarray`` holding audio data with a
-sampling frequency of ``fs`` (in the most cases this will be 44100 or 48000
-frames per second), you can play it back with `sounddevice.play()`:
-
-.. code:: python
-
-   sd.play(myarray, fs)
-
-This function returns immediately but continues playing the audio signal in the
-background.  You can stop playback with `sounddevice.stop()`:
-
-.. code:: python
-
-   sd.stop()
-
-If you know that you will use the same sampling frequency for a while, you can
-set it as default using `sounddevice.default.samplerate`:
-
-.. code:: python
-
-   sd.default.samplerate = fs
-
-After that, you can drop the *samplerate* argument:
-
-.. code:: python
-
-   sd.play(myarray)
-
-Recording
-^^^^^^^^^
-
-To record audio data from your sound device into a NumPy array, use
-`sounddevice.rec()`:
-
-.. code:: python
-
-   duration = 10.5  # seconds
-   myrecording = sd.rec(int(duration * fs), samplerate=fs, channels=2)
-
-Again, for repeated use you can set defaults using `sounddevice.default`:
-
-.. code:: python
-
-   sd.default.samplerate = fs
-   sd.default.channels = 2
-
-After that, you can drop the additional arguments:
-
-.. code:: python
-
-   myrecording = sd.rec(int(duration * fs))
-
-This function also returns immediately but continues recording in the
-background.  In the meantime, you can run other commands.  If you want to check
-if the recording is finished, you should use `sounddevice.wait()`:
-
-.. code:: python
-
-   sd.wait()
-
-If the recording was already finished, this returns immediately; if not, it
-waits and returns as soon as the recording is finished.
-
-Alternatively, you could have used the *blocking* argument in the first place:
-
-.. code:: python
-
-   myrecording = sd.rec(duration * fs, blocking=True)
-
-By default, the recorded array has the data type ``'float32'`` (see
-`sounddevice.default.dtype`), but this can be changed with the *dtype* argument:
-
-.. code:: python
-
-   myrecording = sd.rec(duration * fs, dtype='float64')
-
-Simultaneous Playback and Recording
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-To play back an array and record at the same time, use `sounddevice.playrec()`:
-
-.. code:: python
-
-   myrecording = sd.playrec(myarray, fs, channels=2)
-
-The number of output channels is obtained from ``myarray``, but the number of
-input channels still has to be specified.
-
-Again, default values can be used:
-
-.. code:: python
-
-   sd.default.samplerate = fs
-   sd.default.channels = 2
-   myrecording = sd.playrec(myarray)
-
-In this case the number of output channels is still taken from ``myarray``
-(which may or may not have 2 channels), but the number of input channels is
-taken from `sounddevice.default.channels`.
-
-Device Selection
-^^^^^^^^^^^^^^^^
-
-In many cases, the default input/output device(s) will be the one(s) you want,
-but it is of course possible to choose a different device.
-Use `sounddevice.query_devices()` to get a list of supported devices.
-The same list can be obtained from a terminal by typing the command ::
-
-   python3 -m sounddevice
-
-You can use the corresponding device ID to select a desired device by assigning
-to `sounddevice.default.device` or by passing it as *device* argument to
-`sounddevice.play()`, `sounddevice.Stream()` etc.
-
-Instead of the numerical device ID, you can also use a space-separated list of
-case-insensitive substrings of the device name (and the host API name, if
-needed).  See `sounddevice.default.device` for details.
-
-.. code:: python
-
-   import sounddevice as sd
-   sd.default.samplerate = 44100
-   sd.default.device = 'digital output'
-   sd.play(myarray)
-
-Callback Streams
-^^^^^^^^^^^^^^^^
-
-Callback "wire" with `sounddevice.Stream`:
-
-.. code:: python
-
-   import sounddevice as sd
-   duration = 5.5  # seconds
-
-   def callback(indata, outdata, frames, time, status):
-       if status:
-           print(status)
-       outdata[:] = indata
-
-   with sd.Stream(channels=2, callback=callback):
-       sd.sleep(int(duration * 1000))
-
-Same thing with `sounddevice.RawStream`:
-
-.. code:: python
-
-   import sounddevice as sd
-   duration = 5.5  # seconds
-
-   def callback(indata, outdata, frames, time, status):
-       if status:
-           print(status)
-       outdata[:] = indata
-
-   with sd.RawStream(channels=2, dtype='int24', callback=callback):
-       sd.sleep(int(duration * 1000))
-
-.. note:: We are using 24-bit samples here for no particular reason
-   (just because we can).
-
-Blocking Read/Write Streams
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Instead of using a callback function, you can also use the blocking methods
-`sounddevice.Stream.read()` and `sounddevice.Stream.write()` (and of course the
-corresponding methods in `sounddevice.InputStream`, `sounddevice.OutputStream`,
-`sounddevice.RawStream`, `sounddevice.RawInputStream` and
-`sounddevice.RawOutputStream`).

doc/CONTRIBUTING.rst

@@ -0,0 +1 @@
+../CONTRIBUTING.rst

doc/api.rst

@@ -0,0 +1,44 @@
+API Documentation
+=================
+
+.. automodule:: sounddevice
+   :members:
+   :undoc-members:
+   :exclude-members: RawInputStream, RawOutputStream, RawStream,
+                     InputStream, OutputStream, Stream,
+                     CallbackFlags, CallbackStop, CallbackAbort,
+                     PortAudioError, DeviceList,
+                     AsioSettings, CoreAudioSettings, WasapiSettings
+
+.. autoclass:: Stream
+   :members:
+   :undoc-members:
+   :inherited-members:
+
+.. autoclass:: InputStream
+
+.. autoclass:: OutputStream
+
+.. autoclass:: RawStream
+   :members: read, write
+
+.. autoclass:: RawInputStream
+
+.. autoclass:: RawOutputStream
+
+.. autoclass:: DeviceList
+
+.. autoclass:: CallbackFlags
+   :members:
+
+.. autoclass:: CallbackStop
+
+.. autoclass:: CallbackAbort
+
+.. autoclass:: PortAudioError
+
+.. autoclass:: AsioSettings
+
+.. autoclass:: CoreAudioSettings
+
+.. autoclass:: WasapiSettings

doc/conf.py

@@ -111,7 +111,7 @@
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
-#default_role = None
+default_role = 'any'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True

doc/examples.rst

@@ -1,5 +1,3 @@
-:orphan:
-
 Example Programs
 ================