Refactor tutorial organization (#1987)

* Refactor tutorial organization

* Merge tutorial subdirectoris under to examples/gallery/tutorials
* Do not use index.rst generated by Sphinx-gallery
* Instead use flat structure so that all the tutorials are listed in left menu
* Use `_assets` dir for artifacts of tutorials

.flake8

 [flake8]
 max-line-length = 120
 ignore = E305,E402,E721,E741,F405,W503,W504,F999
-exclude = build,docs/source,_ext,third_party,examples/gallery
+exclude = build,docs/source,_ext,third_party,examples/tutorials

.gitignore

@@ -69,7 +69,7 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/src/
-docs/source/auto_examples
+docs/source/tutorials
 docs/source/gen_modules
 
 # PyBuilder
@@ -123,6 +123,7 @@ gen.yml
 examples/interactive_asr/data/*.txt
 examples/interactive_asr/data/*.model
 examples/interactive_asr/data/*.pt
+examples/tutorials/_assets
 
 # third parties
 third_party/install/

docs/source/_templates/layout.html

@@ -60,8 +60,8 @@
       $(document).ready(function() {
 	  var downloadNote = $(".sphx-glr-download-link-note.admonition.note");
 	  if (downloadNote.length >= 1) {
-	      var tutorialUrlArray = $("#tutorial-type").text().split('/').slice(1);
-	      var githubLink = "https://github.com/pytorch/audio/blob/main/examples/gallery/"  + tutorialUrlArray.join("/") + ".py",
+	      var tutorialUrl = $("#tutorial-type").text();
+	      var githubLink = "https://github.com/pytorch/audio/blob/main/examples/"  + tutorialUrl + ".py",
 		  notebookLink = $(".reference.download")[1].href,
 		  notebookDownloadPath = notebookLink.split('_downloads')[1],
 		  colabLink = "https://colab.research.google.com/github/pytorch/audio/blob/gh-pages/main/_downloads" + notebookDownloadPath;

docs/source/conf.py

@@ -22,7 +22,6 @@
 # sys.path.insert(0, os.path.abspath('.'))
 import os
 import re
-from pathlib import Path
 import pytorch_sphinx_theme
 
 # -- General configuration ------------------------------------------------
@@ -103,20 +102,16 @@ def _get_pattern():
     return ret
 
 
-def _get_dirs():
-    _this_dir = Path(__file__).parent.resolve()
-    _base_input_dir = _this_dir / '..' / '..' / 'examples' / 'gallery'
-    _base_output_dir = _this_dir / 'auto_examples'
-    dirs = [p.name for p in _base_input_dir.iterdir() if p.is_dir()]
-    examples_dirs = [_base_input_dir / p for p in dirs]
-    gallery_dirs = [_base_output_dir / p for p in dirs]
-    return {'examples_dirs': examples_dirs, 'gallery_dirs': gallery_dirs}
-
-
 sphinx_gallery_conf = {
-    **_get_dirs(),
+    'examples_dirs': [
+        '../../examples/tutorials',
+    ],
+    'gallery_dirs': [
+        'tutorials',
+    ],
     **_get_pattern(),
     'backreferences_dir': 'gen_modules/backreferences',
+    'first_notebook_cell': None,
     'doc_module': ('torchaudio',),
 }
 autosummary_generate = True
@@ -163,7 +158,7 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = []
+exclude_patterns = ['*/index.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'

docs/source/index.rst

@@ -46,8 +46,9 @@ The :mod:`torchaudio` package consists of I/O, popular datasets and common audio
    :maxdepth: 2
    :caption: Tutorials
 
-   auto_examples/wav2vec2/index
-   auto_examples/tts/index
+   tutorials/speech_recognition_pipeline_tutorial
+   tutorials/forced_alignment_tutorial
+   tutorials/tacotron2_pipeline_tutorial
 
 .. toctree::
    :maxdepth: 1

examples/gallery/.gitignore

-*.*
-!*.rst
-!*.py

examples/gallery/tts/README.rst

-Text-to-Speech
-==============

examples/gallery/wav2vec2/README.rst

-Wav2Vec2 Tutorials
-==================

examples/tutorials/README.rst

+Tutorials
+=========

examples/gallery/wav2vec2/forced_alignment_tutorial.py → examples/tutorials/forced_alignment_tutorial.py

@@ -57,9 +57,10 @@ print(torchaudio.__version__)
 print(device)
 
 SPEECH_URL = 'https://download.pytorch.org/torchaudio/tutorial-assets/Lab41-SRI-VOiCES-src-sp0307-ch127535-sg0042.wav'
-SPEECH_FILE = 'speech.wav'
+SPEECH_FILE = '_assets/speech.wav'
 
 if not os.path.exists(SPEECH_FILE):
+  os.makedirs('_assets', exist_ok=True)
   with open(SPEECH_FILE, 'wb') as file:
     file.write(requests.get(SPEECH_URL).content)
 
@@ -430,7 +431,7 @@ def display_segment(i):
   word = word_segments[i]
   x0 = int(ratio * word.start)
   x1 = int(ratio * word.end)
-  filename = f"{i}_{word.label}.wav"
+  filename = f"_assets/{i}_{word.label}.wav"
   torchaudio.save(filename, waveform[:, x0:x1], bundle.sample_rate)
   print(f"{word.label} ({word.score:.2f}): {x0 / bundle.sample_rate:.3f} - {x1 / bundle.sample_rate:.3f} sec")
   return IPython.display.Audio(filename)

examples/gallery/wav2vec2/speech_recognition_pipeline_tutorial.py → examples/tutorials/speech_recognition_pipeline_tutorial.py

@@ -58,9 +58,10 @@ print(torchaudio.__version__)
 print(device)
 
 SPEECH_URL = "https://pytorch-tutorial-assets.s3.amazonaws.com/VOiCES_devkit/source-16k/train/sp0307/Lab41-SRI-VOiCES-src-sp0307-ch127535-sg0042.wav"
-SPEECH_FILE = "speech.wav"
+SPEECH_FILE = "_assets/speech.wav"
 
 if not os.path.exists(SPEECH_FILE):
+  os.makedirs('_assets', exist_ok=True)
   with open(SPEECH_FILE, 'wb') as file:
     file.write(requests.get(SPEECH_URL).content)
 

examples/gallery/tts/tacotron2_pipeline_tutorial.py → examples/tutorials/tacotron2_pipeline_tutorial.py

 """
-Text-to-speech with torchaudio Tacotron2
-========================================
+Text-to-Speech with Tacotron2
+=============================
 
 **Author** `Yao-Yuan Yang <https://github.com/yangarbiter>`__,
 `Moto Hira <moto@fb.com>`__
@@ -269,8 +269,8 @@ fig, [ax1, ax2] = plt.subplots(2, 1, figsize=(16, 9))
 ax1.imshow(spec[0].cpu().detach())
 ax2.plot(waveforms[0].cpu().detach())
 
-torchaudio.save("output_wavernn.wav", waveforms[0:1].cpu(), sample_rate=vocoder.sample_rate)
-IPython.display.Audio("output_wavernn.wav")
+torchaudio.save("_assets/output_wavernn.wav", waveforms[0:1].cpu(), sample_rate=vocoder.sample_rate)
+IPython.display.Audio("_assets/output_wavernn.wav")
 
 
 ######################################################################
@@ -298,8 +298,8 @@ fig, [ax1, ax2] = plt.subplots(2, 1, figsize=(16, 9))
 ax1.imshow(spec[0].cpu().detach())
 ax2.plot(waveforms[0].cpu().detach())
 
-torchaudio.save("output_griffinlim.wav", waveforms[0:1].cpu(), sample_rate=vocoder.sample_rate)
-IPython.display.Audio("output_griffinlim.wav")
+torchaudio.save("_assets/output_griffinlim.wav", waveforms[0:1].cpu(), sample_rate=vocoder.sample_rate)
+IPython.display.Audio("_assets/output_griffinlim.wav")
 
 
 ######################################################################
@@ -329,5 +329,5 @@ fig, [ax1, ax2] = plt.subplots(2, 1, figsize=(16, 9))
 ax1.imshow(spec[0].cpu().detach())
 ax2.plot(waveforms[0].cpu().detach())
 
-torchaudio.save("output_waveglow.wav", waveforms[0:1].cpu(), sample_rate=22050)
-IPython.display.Audio("output_waveglow.wav")
+torchaudio.save("_assets/output_waveglow.wav", waveforms[0:1].cpu(), sample_rate=22050)
+IPython.display.Audio("_assets/output_waveglow.wav")