Add Sphinx-gallery to doc

mthrok · mthrok · commit c0b66e6db9f3 · 2021-11-04T02:08:23.000Z
diff --git a/.flake8 b/.flake8
@@ -1,4 +1,4 @@
 [flake8]
 max-line-length = 120
 ignore = E305,E402,E721,E741,F405,W503,W504,F999
-exclude = build,docs/source,_ext,third_party
+exclude = build,docs/source,_ext,third_party,examples/gallery
diff --git a/.gitignore b/.gitignore
@@ -69,6 +69,8 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/src/
+docs/source/auto_examples
+docs/source/gen_modules
 
 # PyBuilder
 target/
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -4,3 +4,6 @@ sphinxcontrib.katex
 sphinxcontrib.bibtex
 matplotlib
 pyparsing<3,>=2.0.2
+sphinx_gallery
+IPython
+deep-phonemizer
diff --git a/docs/source/backend.rst b/docs/source/backend.rst
@@ -3,6 +3,8 @@
 torchaudio.backend
 ==================
 
+.. py:module:: torchaudio.backend
+
 Overview
 ~~~~~~~~
 
diff --git a/docs/source/compliance.kaldi.rst b/docs/source/compliance.kaldi.rst
@@ -6,6 +6,8 @@ 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.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -42,6 +42,7 @@
     'sphinx.ext.viewcode',
     'sphinxcontrib.katex',
     'sphinxcontrib.bibtex',
+    'sphinx_gallery.gen_gallery',
 ]
 
 # katex options
@@ -58,6 +59,19 @@
 
 bibtex_bibfiles = ['refs.bib']
 
+sphinx_gallery_conf = {
+    'examples_dirs': [
+        '../../examples/gallery/wav2vec2',
+    ],
+    'gallery_dirs': [
+        'auto_examples/wav2vec2',
+    ],
+    'filename_pattern': 'tutorial.py',
+    'backreferences_dir': 'gen_modules/backreferences',
+    'doc_module': ('torchaudio',),
+}
+autosummary_generate = True
+
 napoleon_use_ivar = True
 napoleon_numpy_docstring = False
 napoleon_google_docstring = True
diff --git a/docs/source/datasets.rst b/docs/source/datasets.rst
@@ -1,6 +1,8 @@
 torchaudio.datasets
 ====================
 
+.. py:module:: torchaudio.datasets
+
 All datasets are subclasses of :class:`torch.utils.data.Dataset`
 and have ``__getitem__`` and ``__len__`` methods implemented.
 Hence, they can all be passed to a :class:`torch.utils.data.DataLoader`
diff --git a/docs/source/functional.rst b/docs/source/functional.rst
@@ -4,6 +4,8 @@
 torchaudio.functional
 =====================
 
+.. py:module:: torchaudio.functional
+
 .. currentmodule:: torchaudio.functional
 
 Functions to perform common audio operations.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -42,6 +42,11 @@ The :mod:`torchaudio` package consists of I/O, popular datasets and common audio
    utils
    prototype
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Tutorials
+
+   auto_examples/wav2vec2/index
 
 .. toctree::
    :maxdepth: 1
diff --git a/docs/source/kaldi_io.rst b/docs/source/kaldi_io.rst
@@ -4,6 +4,8 @@
 torchaudio.kaldi_io
 ======================
 
+.. py:module:: torchaudio.kaldi_io
+
 .. currentmodule:: torchaudio.kaldi_io
 
 To use this module, the dependency kaldi_io_ needs to be installed.
diff --git a/docs/source/models.rst b/docs/source/models.rst
@@ -4,6 +4,8 @@
 torchaudio.models
 =================
 
+.. py:module:: torchaudio.models
+
 .. currentmodule:: torchaudio.models
 
 The models subpackage contains definitions of models for addressing common audio tasks.
diff --git a/docs/source/pipelines.rst b/docs/source/pipelines.rst
@@ -3,6 +3,8 @@ torchaudio.pipelines
 
 .. currentmodule:: torchaudio.pipelines
 
+.. py:module:: torchaudio.pipelines
+		   
 The pipelines subpackage contains API to access the models with pretrained weights, and information/helper functions associated the pretrained weights.
 
 wav2vec 2.0 / HuBERT - Representation Learning
@@ -73,13 +75,19 @@ HUBERT_XLARGE
 wav2vec 2.0 / HuBERT - Fine-tuned ASR
 -------------------------------------
 
+Wav2Vec2ASRBundle
+~~~~~~~~~~~~~~~~~
+
 .. autoclass:: Wav2Vec2ASRBundle
    :members: sample_rate
 
    .. automethod:: get_model
 
    .. automethod:: get_labels
 
+.. minigallery:: torchaudio.pipelines.WAV2VEC2_ASR_BASE_960H
+   :add-heading: Examples using ``Wav2Vec2ASRBundle``
+   :heading-level: ~
 
 WAV2VEC2_ASR_BASE_10M
 ~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/source/prototype.rst b/docs/source/prototype.rst
@@ -4,6 +4,8 @@
 torchaudio.prototype.emformer
 =============================
 
+.. py:module:: torchaudio.prototype.emformer
+
 .. currentmodule:: torchaudio.prototype.emformer
 
 Emformer is a prototype feature; see `here <https://pytorch.org/audio>`_
diff --git a/docs/source/sox_effects.rst b/docs/source/sox_effects.rst
@@ -3,6 +3,8 @@
 torchaudio.sox_effects
 ======================
 
+.. py:module:: torchaudio.sox_effects
+
 .. currentmodule:: torchaudio.sox_effects
 
 Resource initialization / shutdown
diff --git a/docs/source/transforms.rst b/docs/source/transforms.rst
@@ -4,6 +4,8 @@
 torchaudio.transforms
 ======================
 
+.. py:module:: torchaudio.transforms
+
 .. currentmodule:: torchaudio.transforms
 
 Transforms are common audio transforms. They can be chained together using :class:`torch.nn.Sequential`
diff --git a/docs/source/utils.rst b/docs/source/utils.rst
@@ -1,6 +1,8 @@
 torchaudio.utils
 ================
 
+.. py:module:: torchaudio.utils
+
 torchaudio.utils.sox_utils
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/examples/gallery/.gitignore b/examples/gallery/.gitignore
@@ -0,0 +1,3 @@
+*.*
+!*.rst
+!*.py
diff --git a/examples/gallery/wav2vec2/README.rst b/examples/gallery/wav2vec2/README.rst
@@ -0,0 +1,2 @@
+Wav2Vec2 Tutorials
+==================
diff --git a/examples/gallery/wav2vec2/forced_alignment_tutorial.py b/examples/gallery/wav2vec2/forced_alignment_tutorial.py
diff --git a/examples/gallery/wav2vec2/speech_recognition_pipeline_tutorial.py b/examples/gallery/wav2vec2/speech_recognition_pipeline_tutorial.py
