Add Sphinx gallery automatically (#2101)

Summary:
This commit updates the documentation configuration so that if an API (function or class) is used in tutorials, then it automatically add the links to the tutorials.

It also adds `py:func:` so that it's easy to jump from tutorials to API reference.

Note: the use of `py:func:` is not required to be recognized by Shpinx-gallery.

* https://482162-90321822-gh.circle-artifacts.com/0/docs/transforms.html#feature-extractions

<img width="776" alt="Screen Shot 2021-12-24 at 12 41 43 PM" src="https://user-images.githubusercontent.com/855818/147367407-cd86f114-7177-426a-b5ee-a25af17ae476.png">

* https://482162-90321822-gh.circle-artifacts.com/0/docs/transforms.html#mvdr

<img width="769" alt="Screen Shot 2021-12-24 at 12 42 31 PM" src="https://user-images.githubusercontent.com/855818/147367422-01fd245f-2f25-4875-a206-910e17ae0161.png">

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

Reviewed By: hwangjeff

Differential Revision: D33311283

Pulled By: mthrok

fbshipit-source-id: e0c124d2a761e0f8d81c3d14c4ffc836ffffe288

docs/source/conf.py

@@ -311,3 +311,24 @@ def patched_make_field(self, types, domain, items, **kw):
 
 
 TypedField.make_field = patched_make_field
+
+
+# Based off of
+# https://github.com/sphinx-gallery/sphinx-gallery/blob/5b21962284f865beeaeb79cca50c8c394fa60cba/sphinx_gallery/directives.py#L66-L70
+def _has_backref(obj):
+    this_dir = os.path.dirname(__file__)
+    path = os.path.join(this_dir, "gen_modules", "backreferences", f"{obj}.examples")
+    return os.path.isfile(path) and os.path.getsize(path) > 0
+
+
+# Based off of
+# https://github.com/pytorch/vision/blob/5335006be7ef01c9f6cb700fe793d7c645e83e84/docs/source/conf.py#L262
+def inject_minigalleries(app, what, name, obj, options, lines):
+    if what in ("class", "function") and _has_backref(name):
+        lines.append(f"Tutorials using ``{name.split('.')[-1]}``:")
+        lines.append(f"    .. minigallery:: {name}")
+        lines.append("\n")
+
+
+def setup(app):
+    app.connect("autodoc-process-docstring", inject_minigalleries)

docs/source/pipelines.rst

@@ -85,10 +85,6 @@ Wav2Vec2ASRBundle
 
    .. automethod:: get_labels
 
-.. minigallery:: torchaudio.pipelines.WAV2VEC2_ASR_BASE_960H
-   :add-heading: Examples using ``Wav2Vec2ASRBundle``
-   :heading-level: ~
-
 WAV2VEC2_ASR_BASE_10M
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -231,10 +227,6 @@ Tacotron2TTSBundle
 
    .. automethod:: get_vocoder
 
-.. minigallery:: torchaudio.pipelines.Tacotron2TTSBundle
-   :add-heading: Examples using ``Tacotron2TTSBundle``
-   :heading-level: ~
-
 Tacotron2TTSBundle - TextProcessor
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/source/torchaudio.rst

@@ -6,7 +6,8 @@ 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.
+
+Please refer to :ref:`backend` for the detail, and the :doc:`Audio I/O tutorial <../tutorials/audio_io_tutorial>` for the usage.
 
 .. function:: torchaudio.info(filepath: str, ...)
 

examples/tutorials/audio_datasets_tutorial.py

@@ -84,7 +84,8 @@ def play_audio(waveform, sample_rate):
 
 
 ######################################################################
-# Here, we show how to use the ``YESNO`` dataset.
+# Here, we show how to use the
+# :py:func:`torchaudio.datasets.YESNO` dataset.
 #
 
 

examples/tutorials/audio_feature_augmentation_tutorial.py

@@ -112,11 +112,14 @@ def plot_spectrogram(spec, title=None, ylabel="freq_bin", aspect="auto", xmax=No
 # `SpecAugment <https://ai.googleblog.com/2019/04/specaugment-new-data-augmentation.html>`__
 # is a popular spectrogram augmentation technique.
 #
-# ``torchaudio`` implements ``TimeStretch``, ``TimeMasking`` and
-# ``FrequencyMasking``.
+# ``torchaudio`` implements :py:func:`torchaudio.transforms.TimeStretch`,
+# :py:func:`torchaudio.transforms.TimeMasking` and
+# :py:func:`torchaudio.transforms.FrequencyMasking`.
 #
+
+######################################################################
 # TimeStretch
-# ~~~~~~~~~~~
+# -----------
 #
 
 
@@ -135,7 +138,7 @@ plot_spectrogram(torch.abs(spec_[0]), title=f"Stretched x{rate}", aspect="equal"
 
 ######################################################################
 # TimeMasking
-# ~~~~~~~~~~~
+# -----------
 #
 
 torch.random.manual_seed(4)
@@ -150,7 +153,7 @@ plot_spectrogram(spec[0], title="Masked along time axis")
 
 ######################################################################
 # FrequencyMasking
-# ~~~~~~~~~~~~~~~~
+# ----------------
 #
 
 

examples/tutorials/audio_feature_extractions_tutorial.py

@@ -212,7 +212,7 @@ def plot_kaldi_pitch(waveform, sample_rate, pitch, nfcc):
 # -----------
 #
 # To get the frequency make-up of an audio signal as it varies with time,
-# you can use ``Spectrogram``.
+# you can use :py:func:`torchaudio.functional.Spectrogram`.
 #
 
 
@@ -274,11 +274,11 @@ play_audio(waveform, sample_rate)
 # Mel Filter Bank
 # ---------------
 #
-# ``torchaudio.functional.melscale_fbanks`` generates the filter bank
+# :py:func:`torchaudio.functional.melscale_fbanks` generates the filter bank
 # for converting frequency bins to mel-scale bins.
 #
 # Since this function does not require input audio/features, there is no
-# equivalent transform in ``torchaudio.transforms``.
+# equivalent transform in :py:func:`torchaudio.transforms`.
 #
 
 
@@ -325,7 +325,8 @@ print("Mean Square Difference: ", mse)
 # --------------
 #
 # Generating a mel-scale spectrogram involves generating a spectrogram
-# and performing mel-scale conversion. In ``torchaudio``, ``MelSpectrogram`` provides
+# and performing mel-scale conversion. In ``torchaudio``,
+# :py:func:`torchaudio.transforms.MelSpectrogram` provides
 # this functionality.
 #
 
@@ -456,7 +457,7 @@ play_audio(waveform, sample_rate)
 #
 # Kaldi Pitch feature [1] is a pitch detection mechanism tuned for automatic
 # speech recognition (ASR) applications. This is a beta feature in ``torchaudio``,
-# and it is available only in ``functional``.
+# and it is available as :py:func:`torchaudio.functional.compute_kaldi_pitch`.
 #
 # 1. A pitch extraction algorithm tuned for automatic speech recognition
 #

examples/tutorials/audio_io_tutorial.py

@@ -178,8 +178,8 @@ def inspect_file(path):
 # Querying audio metadata
 # -----------------------
 #
-# Function ``torchaudio.info`` fetches audio metadata. You can provide
-# a path-like object or file-like object.
+# Function :py:func:`torchaudio.info` fetches audio metadata.
+# You can provide a path-like object or file-like object.
 #
 
 
@@ -237,7 +237,7 @@ print(metadata)
 # Querying file-like object
 # ~~~~~~~~~~~~~~~~~~~~~~~~~
 #
-# ``info`` works on file-like objects.
+# :py:func:`torchaudio.info` works on file-like objects.
 #
 
 print("Source:", SAMPLE_WAV_URL)
@@ -268,7 +268,7 @@ print(metadata)
 # Loading audio data into Tensor
 # ------------------------------
 #
-# To load audio data, you can use ``torchaudio.load``.
+# To load audio data, you can use :py:func:`torchaudio.load`.
 #
 # This function accepts a path-like object or file-like object as input.
 #
@@ -366,7 +366,7 @@ print("matched!")
 # --------------------
 #
 # To save audio data in formats interpretable by common applications,
-# you can use ``torchaudio.save``.
+# you can use :py:func:`torchaudio.save`.
 #
 # This function accepts a path-like object or file-like object.
 #
@@ -404,7 +404,8 @@ inspect_file(path)
 
 
 ######################################################################
-# ``torchaudio.save`` can also handle other formats. To name a few:
+# :py:func`torchaudio.save` can also handle other formats.
+# To name a few:
 #
 
 waveform, sample_rate = get_sample(resample=8000)

examples/tutorials/audio_resampling_tutorial.py

@@ -196,11 +196,15 @@ def benchmark_resample(
 
 
 ######################################################################
+# Resampling Overview
+# -------------------
+#
 # To resample an audio waveform from one freqeuncy to another, you can use
-# ``transforms.Resample`` or ``functional.resample``.
-# ``transforms.Resample`` precomputes and caches the kernel used for
-# resampling, while ``functional.resample`` computes it on the fly, so
-# using ``transforms.Resample`` will result in a speedup when resampling
+# :py:func:`torchaudio.transforms.Resample` or
+# :py:func:`torchaudio.functional.resample`.
+# ``transforms.Resample`` precomputes and caches the kernel used for resampling,
+# while ``functional.resample`` computes it on the fly, so using
+# ``torchaudio.transforms.Resample`` will result in a speedup when resampling
 # multiple waveforms using the same parameters (see Benchmarking section).
 #
 # Both resampling methods use `bandlimited sinc

examples/tutorials/mvdr_tutorial.py

@@ -10,7 +10,8 @@ MVDR with torchaudio
 # Overview
 # --------
 #
-# This is a tutorial on how to apply MVDR beamforming by using `torchaudio <https://github.com/pytorch/audio>`__.
+# This is a tutorial on how to apply MVDR beamforming with
+# :py:func:`torchaudio.transforms.MVDR`.
 #
 # Steps
 #

examples/tutorials/speech_recognition_pipeline_tutorial.py

@@ -26,7 +26,7 @@ pre-trained models from wav2vec 2.0
 # Torchaudio provides easy access to the pre-trained weights and
 # associated information, such as the expected sample rate and class
 # labels. They are bundled together and available under
-# ``torchaudio.pipelines`` module.
+# :py:func:`torchaudio.pipelines` module.
 #