Adopt :autosummary: to multiple modules (#2664)

Summary:
Adopt `:autosummary:` to various modules

    * torchaudio.compliance.kaldi
    * torchaudio.sox_effects
    * torchaudio.utils

Pull Request resolved: https://github.com/pytorch/audio/pull/2664

Reviewed By: nateanl

Differential Revision: D39841873

Pulled By: mthrok

fbshipit-source-id: ff4fa6976324fca5f35b737b715f976e2a722bac

docs/source/_templates/autosummary/utils.rst

+..
+  autogenerated from source/_templates/autosummary/utils.rst
+
+.. py:module:: {{ fullname }}
+
+{{ name | underline }}
+
+.. automodule:: {{fullname}}
+   :noindex:
+
+.. currentmodule:: {{ fullname }}
+
+{%- for func in functions %}
+
+{{ func | underline("-") }}
+
+.. autofunction:: {{ func }}
+
+{%- endfor %}

docs/source/backend.rst

@@ -12,8 +12,8 @@ Overview
 
 There are currently four implementations available.
 
-* :ref:`"sox_io" <sox_io_backend>` (default on Linux/macOS)
-* :ref:`"soundfile" <soundfile_backend>` (default on Windows)
+* :py:mod:`"sox_io" <torchaudio.backends.sox_io_backend>` (default on Linux/macOS)
+* :py:mod:`"soundfile" <torchaudio.backends.soundfile_backend>` (default on Windows)
 
 .. note::
    Instead of calling functions in ``torchaudio.backend`` directly, please use ``torchaudio.info``, ``torchaudio.load``, and ``torchaudio.save`` with proper backend set with :func:`torchaudio.set_audio_backend`.
@@ -35,7 +35,7 @@ AudioMetaData
 
 .. autoclass:: torchaudio.backend.common.AudioMetaData
 
-.. _sox_io_backend:
+.. py:module:: torchaudio.backend.sox_io_backend
 
 Sox IO Backend
 ~~~~~~~~~~~~~~
@@ -65,7 +65,7 @@ save
 
 .. autofunction:: torchaudio.backend.sox_io_backend.save
 
-.. _soundfile_backend:
+.. py:module:: torchaudio.backend.soundfile_backend
 
 Soundfile Backend
 ~~~~~~~~~~~~~~~~~

docs/source/compliance.kaldi.rst

-.. role:: hidden
-    :class: hidden-section
+.. py:module:: torchaudio.compliance.kaldi
 
 torchaudio.compliance.kaldi
-============================
+===========================
 
 .. currentmodule:: torchaudio.compliance.kaldi
 
-.. py:module:: torchaudio.compliance.kaldi
-		   
 The useful processing operations of kaldi_ can be performed with torchaudio.
 Various functions with identical parameters are given so that torchaudio can
 produce similar outputs.
 
 .. _kaldi: https://github.com/kaldi-asr/kaldi
 
-Functions
----------
-
-:hidden:`spectrogram`
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. autofunction:: spectrogram
-
-:hidden:`fbank`
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. autofunction:: fbank
-
-:hidden:`mfcc`
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
 
-.. autofunction:: mfcc
+   spectrogram
+   fbank
+   mfcc

docs/source/sox_effects.rst

-.. _sox_effects:
+.. py:module:: torchaudio.sox_effects
 
 torchaudio.sox_effects
 ======================
 
-.. py:module:: torchaudio.sox_effects
-
 .. currentmodule:: torchaudio.sox_effects
 
-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
---------------------------
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+
+   apply_effects_tensor
+   apply_effects_file
 
-.. autofunction:: apply_effects_tensor
+.. minigallery:: torchaudio.sox_effects.apply_effects_tensor
+   
+Utilities
+---------
 
-Applying effects on file
-------------------------
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
 
-.. autofunction:: apply_effects_file
+   init_sox_effects
+   shutdown_sox_effects
+   effect_names

docs/source/utils.rst

-torchaudio.utils
-================
-
 .. py:module:: torchaudio.utils
 
-torchaudio.utils.sox_utils
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Utility module to configure libsox.
-This affects functionalities in :ref:`Sox IO backend<sox_io_backend>` and :ref:`Sox Effects<sox_effects>`.
+torchaudio.utils
+================
 
-.. automodule:: torchaudio.utils.sox_utils
-   :members:
+``torchaudio.utils`` module contains utility functions to configure the global state of third party libraries.
 
-torchaudio.utils.ffmpeg_utils
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. currentmodule:: torchaudio.utils
 
-Utility module to configure FFmpeg libraries.
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: autosummary/utils.rst
 
-.. automodule:: torchaudio.utils.ffmpeg_utils
-   :members:
+   sox_utils
+   ffmpeg_utils

torchaudio/backend/common.py

 class AudioMetaData:
     """Return type of ``torchaudio.info`` function.
 
-    This class is used by :ref:`"sox_io" backend<sox_io_backend>` and
-    :ref:`"soundfile" backend with the new interface<soundfile_backend>`.
+    This class is used by :py:mod:`"sox_io" backend<torchaudio.backends.sox_io_backend>` and
+    :py:mod:`"soundfile" backend<torchaudio.backends.soundfile_backend>`.
 
     :ivar int sample_rate: Sample rate
     :ivar int num_frames: The number of frames

torchaudio/utils/ffmpeg_utils.py

+"""Module to change the configuration of FFmpeg libraries (such as libavformat).
+
+It affects functionalities in :py:mod:`torchaudio.io` (and indirectly :py:func:`torchaudio.load`).
+"""
 from typing import Dict, Tuple
 
 import torch

torchaudio/utils/sox_utils.py

+"""Module to change the configuration of libsox, which is used by I/O functions like
+:py:mod:`~torchaudio.backend.sox_io_backend` and :py:mod:`~torchaudio.sox_effects`.
+"""
+
 from typing import Dict, List
 
 import torch