GitLab

Summary:
- Boldface the version-selection UX and increase size by three percent.
- Add text to breadcrumbs to indicate version and stability.
- New `breadcrumbs.html` in `_templates` overrides Sphinx version.

I create a new variable in `conf.py`, **version_stable**, which has the version number for the most-recent stable release. I define this variable in the **html_context** dictionary so that it is visible to the templates.

I use this approach because I was not able to find any other way of discerning the current stable release during the build. Note that the `versions.html` file--which identifies the current stable release--appears to be available only in the **gh-pages** branch and so it is not available at build time.

However, this means that someone will need to update `conf.py` whenever the current stable release changes.

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

Reviewed By: mthrok

Differential Revision: D44112224

Pulled By: carljparker

fbshipit-source-id: e76f5cb6734a784d161342964459577aa9b64cac

Summary:
Adding C++ documentation. (C++ APIs are categorized as prototype, though it's used by Python beta APIs.)

https://output.circle-artifacts.com/output/job/69654229-a99e-4b15-9ce0-7bc6bcf01101/artifacts/0/docs/libtorchaudio.html

<img width="1202" alt="Screenshot 2023-01-31 at 11 48 47 AM" src="https://user-images.githubusercontent.com/855818/215828167-d23032f8-9e40-4413-b5b1-5cbd12d705e9.png">

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

Reviewed By: hwangjeff

Differential Revision: D42876621

Pulled By: mthrok

fbshipit-source-id: d8b8d610b87ec766501baa88b7506368a9905a6a

Summary:
<img width="756" alt="Screen Shot 2022-11-01 at 3 32 58 PM" src="https://user-images.githubusercontent.com/855818/199173348-f463ae71-438c-4dad-a481-b65522a8e52f.png">

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

Reviewed By: carolineechen

Differential Revision: D40919942

Pulled By: mthrok

fbshipit-source-id: 18e5a709c262fb0b15ada0d303f1d0dee033beb1

Summary:
This commit re-organizes the tutorials.

1. Put all the tutorials in the left bar and make the section **folded by default**.
2. Add pytorch/tutorials-like cards in index
3. Move feature classifications to a dedicated page.

https://output.circle-artifacts.com/output/job/1f1a04a5-137e-428d-9da4-c46f59eeffa4/artifacts/0/docs/index.html

<img width="1073" alt="Screen Shot 2022-10-28 at 7 34 29 AM" src="https://user-images.githubusercontent.com/855818/198410686-3ef40ad2-c9c9-443c-800e-6e51e1b6a491.png">

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

Reviewed By: carolineechen

Differential Revision: D40627547

Pulled By: mthrok

fbshipit-source-id: 098b825f242e91919126014abdab27852304ae64

Summary:
The link to version selector has been absolute link, which had been
a trap when reviewing gh-pages deployment from folk.

This commit changes that to relative link.

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

Test Plan:
- https://mthrok.github.io/audio/main/index.html -> click version selector -> https://mthrok.github.io/audio/versions.html
- https://mthrok.github.io/audio/0.12.1/index.html -> click version selector -> https://pytorch.org/audio/versions.html

Reviewed By: carolineechen, nateanl

Differential Revision: D38695645

Pulled By: mthrok

fbshipit-source-id: 91132ac19b8c61f39d304a162435b9c6599ef2b2

Summary:
Follow-up of https://github.com/pytorch/audio/issues/2407, the <script> was not properly closed on pages other than tutorials

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

Reviewed By: carolineechen

Differential Revision: D36632668

Pulled By: mthrok

fbshipit-source-id: 9c0409a8011d77f8689e2dcdc1bd9844d3d31f79

Summary:
This commit fixes multiple issues with documentation.

https://output.circle-artifacts.com/output/job/23245537-e57b-4b9d-9b81-b3df20996d1f/artifacts/0/docs/tutorials/audio_resampling_tutorial.html

1. Duplicated requirejs
The nbsphinx extension introduced in https://github.com/pytorch/audio/pull/2393 pulled a requirejs
which caused the initialization script to halt.
As a result, the right side bar was left uninitialized.

2. Undefined variable error
It turned out that PyTorch's theme expected the downstream projects
to define `collapsedSections` variable.
Currently console log shows `collapsedSections is not defined`.
As a result of this fix, we start to see the + symbol on left side.

3. Fix the behavior of default expand
Tweaks the right-side bar initialization behavior
so that expand-all only happens once, not at every resize.

4. Overwrite the link to GitHub
The `GitHub` tab in main-menu always linked PyTorch core.
This commit adds overwrite to torchaudio page

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

Reviewed By: carolineechen

Differential Revision: D36612904

Pulled By: mthrok

fbshipit-source-id: 56aa7623a8925a241cf4790ac77a87424ad9237c

Summary:
This commit updates the `window.sideMenus.handleRightMenu`, so that
subsections are expanded on tutorials by default.

https://output.circle-artifacts.com/output/job/98508917-87df-4666-9958-c70683b3245d/artifacts/0/docs/tutorials/audio_io_tutorial.html

Tutorial subsections are important because they have anchors so
allow us to get the link to the specific figures / audio samples.

When responding issues/questions and when there is a corresponding
code snippet in tutorial, it is often easy to answer with links to
the tutorial.

However, by default the tutorial page collapses right side bar, and
I have to click the small "+" symbols to navigate to the subsection,
and the state of expansion does not persist across the page refresh.

This has been a pain point since we updated the Sphinx version to 3
in https://github.com/pytorch/audio/pull/1685.

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

Reviewed By: xiaohui-zhang

Differential Revision: D36429745

Pulled By: mthrok

fbshipit-source-id: 97a5ae9270e68f8e88f0bca766d5a2c1839634e3

Summary:
This commit adds tutorial for device ASR, and update API for device streaming.

The changes for the interface are
1. Add `timeout` and `backoff` parameters to `process_packet` and `stream` methods.
2. Move `fill_buffer` method to private.

When dealing with device stream, there are situations where the device buffer is not
ready and the system returns `EAGAIN`. In such case, the previous implementation of
`process_packet` method raised an exception in Python layer , but for device ASR,
this is inefficient. A better approach is to retry within C++ layer in blocking manner.
The new `timeout` parameter serves this purpose.

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

Reviewed By: nateanl

Differential Revision: D34475829

Pulled By: mthrok

fbshipit-source-id: bb6d0b125d800f87d189db40815af06fbd4cab59

* 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

This commit adds colab/download/source link to tutorials, like in `pytorch/tutorials` repo.

Since the upstream `pytorch-sphinx-theme` does not provide the interface for this,
a hack to overwrite the URL is added.

This hack might stop working if there is some update in `pytorch-sphinx-theme`.