DOC Fix sphinx warnings and turn warnings into errors (#1247)

Author: NicolasHug

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W  # converts warnings into error
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = torchaudio
 SOURCEDIR     = source

docs/source/backend.rst

@@ -157,20 +157,20 @@ You can switch from another backend to the ``"soundfile"`` backend with the foll
     If you are switching from `"soundfile" (legacy interface) <soundfile_legacy_backend>` backend, set ``torchaudio.USE_SOUNDFILE_LEGACY_INTERFACE`` flag **before** switching the backend.
 
 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/conf.py

@@ -58,6 +58,8 @@
 '''
 
 napoleon_use_ivar = True
+napoleon_numpy_docstring = False
+napoleon_google_docstring = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

torchaudio/_internal/module_utils.py

@@ -44,6 +44,7 @@ def deprecated(direction: str, version: Optional[str] = None):
         direction: Migration steps to be given to users.
     """
     def decorator(func):
+
         @wraps(func)
         def wrapped(*args, **kwargs):
             message = (

torchaudio/backend/common.py

@@ -1,6 +1,5 @@
 from typing import Any, Optional
-
-from torchaudio._internal import module_utils as _mod_utils
+import warnings
 
 
 class AudioMetaData:
@@ -31,7 +30,6 @@ def __init__(
         self.encoding = encoding
 
 
-@_mod_utils.deprecated('Please migrate to `AudioMetaData`.', '0.9.0')
 class SignalInfo:
     """One of return types of ``torchaudio.info`` functions.
 
@@ -51,13 +49,18 @@ def __init__(self,
                  rate: Optional[float] = None,
                  precision: Optional[int] = None,
                  length: Optional[int] = None) -> None:
+        message = (
+            f'{self.__module__}.{self.__class__.__name__} has been deprecated '
+            'and will be removed from 0.9.0 release. '
+            'Please migrate to `AudioMetaData`.'
+        )
+        warnings.warn(message)
         self.channels = channels
         self.rate = rate
         self.precision = precision
         self.length = length
 
 
-@_mod_utils.deprecated('Please migrate to `AudioMetaData`.', '0.9.0')
 class EncodingInfo:
     """One of return types of ``torchaudio.info`` functions.
 
@@ -82,6 +85,12 @@ def __init__(self,
                  reverse_nibbles: Any = None,
                  reverse_bits: Any = None,
                  opposite_endian: Optional[bool] = None) -> None:
+        message = (
+            f'{self.__module__}.{self.__class__.__name__} has been deprecated '
+            'and will be removed from 0.9.0 release. '
+            'Please migrate to `AudioMetaData`.'
+        )
+        warnings.warn(message)
         self.encoding = encoding
         self.bits_per_sample = bits_per_sample
         self.compression = compression

torchaudio/backend/sox_io_backend.py

@@ -22,18 +22,22 @@ def info(
         filepath (path-like object or file-like object):
             Source of audio data. When the function is not compiled by TorchScript,
             (e.g. ``torch.jit.script``), the following types are accepted;
+
                   * ``path-like``: file path
                   * ``file-like``: Object with ``read(size: int) -> bytes`` method,
                     which returns byte string of at most ``size`` length.
+
             When the function is compiled by TorchScript, only ``str`` type is allowed.
 
             Note:
+
                   * When the input type is file-like object, this function cannot
                     get the correct length (``num_samples``) for certain formats,
                     such as ``mp3`` and ``vorbis``.
                     In this case, the value of ``num_samples`` is ``0``.
                   * This argument is intentionally annotated as ``str`` only due to
                     TorchScript compiler compatibility.
+
         format (str, optional):
             Override the format detection with the given format.
             Providing the argument might help when libsox can not infer the format
@@ -103,14 +107,15 @@ def load(
         filepath (path-like object or file-like object):
             Source of audio data. When the function is not compiled by TorchScript,
             (e.g. ``torch.jit.script``), the following types are accepted;
+
                   * ``path-like``: file path
                   * ``file-like``: Object with ``read(size: int) -> bytes`` method,
                     which returns byte string of at most ``size`` length.
+
             When the function is compiled by TorchScript, only ``str`` type is allowed.
 
-            Note:
-                * This argument is intentionally annotated as ``str`` only due to
-                  TorchScript compiler compatibility.
+            Note: This argument is intentionally annotated as ``str`` only due to
+            TorchScript compiler compatibility.
         frame_offset (int):
             Number of frames to skip before start reading data.
         num_frames (int):

torchaudio/sox_effects/sox_effects.py

@@ -173,14 +173,16 @@ def apply_effects_file(
     Args:
         path (path-like object or file-like object):
             Source of audio data. When the function is not compiled by TorchScript,
-            (e.g. ``torch.jit.script``), the following types are accepted;
+            (e.g. ``torch.jit.script``), the following types are accepted:
+
                   * ``path-like``: file path
                   * ``file-like``: Object with ``read(size: int) -> bytes`` method,
                     which returns byte string of at most ``size`` length.
+
             When the function is compiled by TorchScript, only ``str`` type is allowed.
-            Note:
-                * This argument is intentionally annotated as ``str`` only for
-                  TorchScript compiler compatibility.
+
+            Note: This argument is intentionally annotated as ``str`` only for
+            TorchScript compiler compatibility.
         effects (List[List[str]]): List of effects.
         normalize (bool):
             When ``True``, this function always return ``float32``, and sample values are