Update documentation and fix docstrings

docs/source/backend.rst

@@ -0,0 +1,138 @@
+.. _backend:
+
+torchaudio.backend
+==================
+
+:mod:`torchaudio.backend` module provides implementations for audio file I/O, using different backend libraries.
+To switch backend, use :py:func:`torchaudio.set_audio_backend`. To check the current backend use :py:func:`torchaudio.get_audio_backend`.
+
+.. warning::
+   Although ``sox`` backend is default for backward compatibility reason, it has a number of issues, therefore it is highly recommended to use ``sox_io`` backend instead. Note, however, that due to the interface refinement, functions defined in ``sox`` backend and those defined in ``sox_io`` backend do not have the same signatures.
+
+.. note::
+   Instead of calling functions in :mod:`torchaudio.backend` directly, please use ``torchaudio.info``, ``torhcaudio.load``, ``torchaudio.load_wav`` and ``torchaudio.save`` with proper backend set with :func:`torchaudio.get_audio_backend`.
+
+There are currently three implementations available.
+
+    * :ref:`sox<sox_backend>`
+    * :ref:`sox_io<sox_io_backend>`
+    * :ref:`soundfile<soundfile_backend>`
+
+``sox`` backend is the original backend which is built on ``libsox``. This module is currently default but is known to have number of issues, such as wrong handling of WAV files other than 16-bit signed integer. Users are encouraged to use ``sox_io`` backend. This backend requires C++ extension module and is not available on Windows system.
+
+``sox_io`` backend is the new backend which is built on ``libsox`` and bound to Python with ``Torchscript``. This module addresses all the known issues ``sox`` backend has. Function calls to this backend can be Torchscriptable. This backend requires C++ extension module and is not available on Windows system.
+
+``soundfile`` backend is built on ``PySoundFile``. You need to install ``PySoundFile`` separately.
+
+Common Data Structure
+~~~~~~~~~~~~~~~~~~~~~
+
+Structures used to exchange data between Python interface and ``libsox``. They are used by :ref:`sox<sox_backend>` and :ref:`soundfile<soundfile_backend>` but not by :ref:`sox_io<sox_io_backend>`.
+
+.. autoclass:: torchaudio.backend.common.SignalInfo
+
+.. autoclass:: torchaudio.backend.common.EncodingInfo               
+
+.. _sox_backend:
+
+Sox Backend
+~~~~~~~~~~~
+
+``sox`` backend is available on ``torchaudio`` installation with C++ extension. It is currently not available on Windows system.
+
+It is currently default backend when it's available. You can switch from another backend to ``sox`` backend with the following;
+
+.. code::
+
+   torchaudio.set_audio_backend("sox")
+
+info
+----
+
+.. autofunction:: torchaudio.backend.sox_backend.info
+
+load
+----
+
+.. autofunction:: torchaudio.backend.sox_backend.load
+
+.. autofunction:: torchaudio.backend.sox_backend.load_wav
+
+
+save
+----
+
+.. autofunction:: torchaudio.backend.sox_backend.save
+
+others
+------
+
+.. automodule:: torchaudio.backend.sox_backend
+   :members:
+   :exclude-members: info, load, load_wav, save
+
+.. _sox_io_backend:
+
+Sox IO Backend
+~~~~~~~~~~~~~~
+
+``sox_io`` backend is available on ``torchaudio`` installation with C++ extension. It is currently not available on Windows system.
+
+This new backend is recommended over ``sox`` backend. You can switch from another backend to ``sox_io`` backend with the following;
+
+.. code::
+
+   torchaudio.set_audio_backend("sox_io")
+
+The function call to this backend can be Torchsript-able. You can apply :func:`torch.jit.script` and dump the object to file, then call it from C++ application.
+
+info
+----
+
+.. autoclass:: torchaudio.backend.sox_io_backend.AudioMetaData
+
+.. autofunction:: torchaudio.backend.sox_io_backend.info
+
+load
+----
+
+.. autofunction:: torchaudio.backend.sox_io_backend.load
+
+.. autofunction:: torchaudio.backend.sox_io_backend.load_wav
+
+
+save
+----
+
+.. autofunction:: torchaudio.backend.sox_io_backend.save
+
+.. _soundfile_backend:
+
+Soundfile Backend
+~~~~~~~~~~~~~~~~~
+
+``soundfile`` backend is available when ``PySoundFile`` is installed. This backend works on ``torchaudio`` installation without C++ extension. (i.e. Windows)
+
+You can switch from another backend to ``soundfile`` backend with the following;
+
+.. code::
+
+   torchaudio.set_audio_backend("soundfile")
+
+info
+----
+
+.. autofunction:: torchaudio.backend.soundfile_backend.info
+
+load
+----
+
+.. autofunction:: torchaudio.backend.soundfile_backend.load
+
+.. autofunction:: torchaudio.backend.soundfile_backend.load_wav
+
+
+save
+----
+
+.. autofunction:: torchaudio.backend.soundfile_backend.save

docs/source/index.rst

@@ -1,19 +1,19 @@
 torchaudio
-===========
+==========
 
 The :mod:`torchaudio` package consists of I/O, popular datasets and common audio transformations.
 
 .. toctree::
    :maxdepth: 2
    :caption: Package Reference
 
-   sox_effects
+   torchaudio
+   backend
+   functional
+   transforms
    datasets
+   models
+   sox_effects
    compliance.kaldi
    kaldi_io
-   transforms
-   functional
    utils
-
-.. automodule:: torchaudio
-   :members:

docs/source/sox_effects.rst

@@ -1,27 +1,52 @@
-.. role:: hidden
-    :class: hidden-section
+.. _sox_effects:
 
 torchaudio.sox_effects
 ======================
 
 .. currentmodule:: torchaudio.sox_effects
 
+.. warning::
+
+   The :py:class:`SoxEffect` and :py:class:`SoxEffectsChain` classes are deprecated. Please migrate to :func:`apply_effects_tensor` and :func:`apply_effects_file`.
+
+Resource initialization / shutdown
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: init_sox_effects
+
+.. autofunction:: shutdown_sox_effects
+
+Listing supported effects
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: effect_names
+
+Applying effects
+~~~~~~~~~~~~~~~~
+
 Apply SoX effects chain on torch.Tensor or on file and load as torch.Tensor.
 
+Applying effects on Tensor
+--------------------------
+
 .. autofunction:: apply_effects_tensor
 
+Applying effects on file
+------------------------
+
 .. autofunction:: apply_effects_file
 
-Create SoX effects chain for preprocessing audio.
+Legacy
+~~~~~~
 
-:hidden:`SoxEffect`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SoxEffect
+---------
 
 .. autoclass:: SoxEffect
   :members:
 
-:hidden:`SoxEffectsChain`
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+SoxEffectsChain
+---------------
 
 .. autoclass:: SoxEffectsChain
   :members: append_effect_to_chain, sox_build_flow_effects, clear_chain, set_input_file

docs/source/torchaudio.rst

@@ -0,0 +1,43 @@
+torchaudio
+==========
+
+I/O functionalities
+~~~~~~~~~~~~~~~~~~~
+
+Audio I/O functions are implemented in :ref:`torchaudio.backend<backend>` module, but for the ease of use, the following functions are made available on :mod:`torchaudio` module. There are different backends available and you can switch backends with :func:`set_audio_backend`.
+
+Refer to :ref:`backend` for the detail.
+
+.. function:: torchaudio.info(filepath: str, ...)
+
+   Fetch meta data of an audio file. Refer to :ref:`backend` for the detail.
+
+.. function:: torchaudio.load(filepath: str, ...)
+
+   Load audio file into torch.Tensor object. Refer to :ref:`backend` for the detail.
+
+.. function:: torchaudio.load_wav(filepath: str, ...)
+
+   Load audio file into torch.Tensor, Refer to :ref:`backend` for the detail.
+
+.. function:: torchaudio.save(filepath: str, src: torch.Tensor, sample_rate: int, ...)
+
+   Save torch.Tensor object into an audio format. Refer to :ref:`backend` for the detail.
+
+.. currentmodule:: torchaudio
+
+Backend Utilities
+~~~~~~~~~~~~~~~~~
+
+.. autofunction:: list_audio_backends
+
+.. autofunction:: get_audio_backend
+
+.. autofunction:: set_audio_backend
+
+Sox Effects Utilities
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: initialize_sox
+
+.. autofunction:: shutdown_sox

docs/source/utils.rst

@@ -1,21 +1,11 @@
-.. role:: hidden
-    :class: hidden-section
+torchaudio.utils
+================
 
 torchaudio.utils.sox_utils
-==========================
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Utility module to configure libsox. This affects functionalities in ``sox_io`` backend and ``torchaudio.sox_effects``.
+Utility module to configure libsox.
+This affects functionalities in :ref:`Sox IO backend<sox_io_backend>` and :ref:`Sox Effects<sox_effects>`.
 
-.. currentmodule:: torchaudio.utils.sox_utils
-
-.. autofunction:: set_seed
-
-.. autofunction:: set_verbosity
-
-.. autofunction:: set_buffer_size
-
-.. autofunction:: set_use_threads
-
-.. autofunction:: list_effects
-
-.. autofunction:: list_formats
+.. automodule:: torchaudio.utils.sox_utils
+   :members:

torchaudio/__init__.py

@@ -35,10 +35,10 @@
 @_mod_utils.deprecated(
     "Please remove the function call to initialize_sox. "
     "Resource initialization is now automatically handled.")
-def initialize_sox() -> int:
+def initialize_sox():
     """Initialize sox effects.
 
-    This function is deprecated. See ``torchaudio.sox_effects.init_sox_effects``
+    This function is deprecated. See :py:func:`torchaudio.sox_effects.init_sox_effects`
     """
     _init_sox_effects()
 
@@ -51,6 +51,6 @@ def initialize_sox() -> int:
 def shutdown_sox():
     """Shutdown sox effects.
 
-    This function is deprecated. See ``torchaudio.sox_effects.shutdown_sox_effects``
+    This function is deprecated. See :py:func:`torchaudio.sox_effects.shutdown_sox_effects`
     """
     _shutdown_sox_effects()

torchaudio/backend/common.py

@@ -2,6 +2,18 @@
 
 
 class SignalInfo:
+    """Data class returned ``info`` functions.
+
+    Used by :ref:`sox backend<sox_backend>` and :ref:`soundfile backend<soundfile_backend>`
+
+    See https://fossies.org/dox/sox-14.4.2/structsox__signalinfo__t.html
+
+    :ivar Optional[int] channels: The number of channels
+    :ivar Optional[float] rate: Sampleing rate
+    :ivar Optional[int] precision: Bit depth
+    :ivar Optional[int] length: For :ref:`sox backend<sox_backend>`, the number of samples.
+        (frames * channels). For :ref:`soundfile backend<soundfile_backend>`, the number of frames.
+    """
     def __init__(self,
                  channels: Optional[int] = None,
                  rate: Optional[float] = None,
@@ -14,6 +26,20 @@ def __init__(self,
 
 
 class EncodingInfo:
+    """Data class returned ``info`` functions.
+
+    Used by :ref:`sox backend<sox_backend>` and :ref:`soundfile backend<soundfile_backend>`
+
+    See https://fossies.org/dox/sox-14.4.2/structsox__encodinginfo__t.html
+
+    :ivar Optional[int] encoding: sox_encoding_t
+    :ivar Optional[int] bits_per_sample: bit depth
+    :ivar Optional[float] compression: Compression option
+    :ivar Any reverse_bytes:
+    :ivar Any reverse_nibbles:
+    :ivar Any reverse_bits:
+    :ivar Optional[bool] opposite_endian:
+    """
     def __init__(self,
                  encoding: Any = None,
                  bits_per_sample: Optional[int] = None,