Add Sphinx-gallery to doc

[mthrok]

Add Sphinx-gallery to documentation so that we can maintain the notebook for the main branch, and copy it over to tutorial repo at new releases.

https://419306-90321822-gh.circle-artifacts.com/0/docs/index.html

Basic Goal

• Add basic sphinx-gallery
  • Note: so as to make it easy to copy the gallery files to tutorial repo at release, we mimic their config as much as possible.
• Port forced alignment example (and fix some minor issues)
  • Fix the last plot which SG does not render properly
• Port ASR example (and fix)

Stretch Goal (separate PRs)

• Add Run in Google Colab [src] (might be better to update PyTorch-sphinx-theme) (Add Colab/Download/Github link similar to tutorials #1969)
  • Fix the link prefix (pytorch/tutorials)
• Port Audio manipulation examples Port Audio I/O tutorials #1970
• Port TTS examples Port TTS tutorial #1973
• Port Speech command classification example
• Port MVDR example

[nateanl]

What's the function of adding it for sphinx-gallery?

[mthrok]

This allows to refer to the module as a whole from examples, like :py:mod:torchaudio.functional.

[nateanl]

Got it. Looks nice.

[nateanl]

The tutorial has the same rendering issue for the last plot: https://pytorch.org/tutorials/intermediate/forced_alignment_with_torchaudio_tutorial.html
We can create a PR there and fix it.

[mthrok]

The tutorial has the same rendering issue for the last plot: https://pytorch.org/tutorials/intermediate/forced_alignment_with_torchaudio_tutorial.html We can create a PR there and fix it.

@nateanl Yeah, once this one is merged, I will make a PR in tutorials repo to port the fix.

[carolineechen]

Overall the changes/rendering looks good, but I was originally under the assumption that the gallery was only for tutorials that aren't also in the pytorch.org tutorials section (either because they use unreleased features or if for some reason we do not think it belongs in pytorch.org). What is the reason for including the same tutorials in both the gallery and website? Updating existing tutorials would then require twice the amount of work to ensure that they are synced.

On another note, I realized the W2V2 speech recognition tutorial link for pytorch.org seems broken, at least on my end https://pytorch.org/tutorials/intermediate_source/speech_recognition_pipeline_tutorial.html

[mthrok]

Overall the changes/rendering looks good, but I was originally under the assumption that the gallery was only for tutorials that aren't also in the pytorch.org tutorials section (either because they use unreleased features or if for some reason we do not think it belongs in pytorch.org). What is the reason for including the same tutorials in both the gallery and website? Updating existing tutorials would then require twice the amount of work to ensure that they are synced.

On another note, I realized the W2V2 speech recognition tutorial link for pytorch.org seems broken, at least on my end https://pytorch.org/tutorials/intermediate_source/speech_recognition_pipeline_tutorial.html

There are couple of advantages of maintaining the tutorial here as well.

1. We can keep the corresponding tutorials up-to-date with main branch.
   With the recent BC-breaking change on wav2vec2 pipeline ([BC-breaking] Remove unused dimension from pretrained Wav2Vec2 ASR #1914), we will need to update the speech recognition tutorial. By having the tutorial in our repo, we can update the tutorial as we land the change. If we only have the tutorials, then we need to remember to update the tutorial until right before the release, when they prepare the release branc on repo, which is very inconvenient. (This is why I put the note Update speech recognition tutorial #1950)
2. Updating the tutorials at release will be just copy-ing the corresponding files to tutorial repo.
   I am setting up the gallery mimicking the configuration of tutorial repo, so that updating the tutorials in tutorial repo is just about replacing it with the ones kept in audio repo. Sure this adds a slight overhead, but I do not think it doubles the efforts.
3. The turn-around time is much better
   With our repo only containing the tutorials of our own, the time it takes for building/debugging the tutorial (the combination of Python code and rST formats, which is not what we are used to write) is much shorter. And it is much easier to debug the issue with the tutorial, (such as the rendering issue in forced alignment tutorial that I did not notice on tutorial repo because turn-around time was too long, but fixed in this PR kinda quickly)

So in short, we can consider the tutorials in our repo as a staging place with nightly binary packages.

[mthrok]

On another note, I realized the W2V2 speech recognition tutorial link for pytorch.org seems broken, at least on my end https://pytorch.org/tutorials/intermediate_source/speech_recognition_pipeline_tutorial.html

Where did you get this?

The tutorial is at
https://pytorch.org/tutorials/intermediate/speech_recognition_pipeline_tutorial.html

[nateanl]

https://pytorch.org/tutorials/ and click the asr demo. I got the same 404 as @carolineechen.

[carolineechen]

@mthrok ok, that makes sense to me. In that case we just need to make sure to remember to add to the release milestone or create a tutorials label to keep track of the necessary tutorial updates prior to release.

and yea, the tutorial link you commented works, but clicking through pytorch.org/tutorials -> audio -> ASR tutorial redirects to the broken link I commented

[mthrok]

@carolineechen @nateanl Okay, the fix for the tutorial link pytorch/tutorials#1738

[mthrok]

Thanks!