Update documentation and fix docstrings (#788)

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,18 +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
-
-.. automodule:: torchaudio
-   :members:
+   utils

docs/source/sox_effects.rst

@@ -1,5 +1,4 @@
-.. role:: hidden
-    :class: hidden-section
+.. _sox_effects:
 
 torchaudio.sox_effects
 ======================
@@ -14,8 +13,8 @@ Create SoX effects chain for preprocessing audio.
 .. 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

torchaudio/__init__.py

@@ -34,10 +34,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()
 
@@ -50,6 +50,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,