Update doc (#3677)

* Update doc

* Update citation

docs/source/_templates/autosummary/io_class.rst

@@ -14,6 +14,8 @@
 
 .. autoclass:: {{ fullname }}
 
+{%- if name not in ["StreamReader", "StreamWriter"] %}
+
 {%- if attributes %}
 
 Properties
@@ -54,37 +56,4 @@ Methods
 {%- endfor %}
 {%- endif %}
 
-
-{%- if name in ["StreamReader", "StreamWriter"] %}
-
-Support Structures
-------------------
-
-{%- if name == "StreamReader" %}
-{%- for item in [
-    "ChunkTensor",
-    "SourceStream",
-    "SourceAudioStream",
-    "SourceVideoStream",
-    "OutputStream",
-    "OutputAudioStream",
-    "OutputVideoStream",
-] %}
-
-{{ item | underline("~") }}
-
-.. autoclass:: torio.io._streaming_media_decoder.{{item}}()
-   :members:
-
-{%- endfor %}
-
-{%- elif name == "StreamWriter" %}
-
-CodecConfig
-~~~~~~~~~~~
-
-.. autoclass:: torchaudio.io::CodecConfig
-   :members:
-
-{%- endif %}
 {%- endif %}

docs/source/_templates/autosummary/torio_io_class.rst

+..
+  autogenerated from source/_templates/autosummary/torio_io_class.rst
+
+{#-
+    ################################################################################
+    # autosummary template for torio.io module
+    # Since StreamingMediaDecoder/StreamingMediaEncoder have many methods/properties,
+    # we want to list them up in the table of contents.
+    # The default class template does not do this, so we use custom one here.
+    ################################################################################
+#}
+
+{{ name | underline }}
+
+.. autoclass:: {{ fullname }}
+
+{%- if attributes %}
+
+Properties
+----------
+
+{%- for item in attributes %}
+{%- if not item.startswith('_') and item not in inherited_members %}
+
+{{ item | underline("~") }}
+
+.. container:: py attribute
+
+   .. autoproperty:: {{[fullname, item] | join('.')}}
+
+{%- endif %}
+{%- endfor %}
+{%- endif %}
+
+{%- if members %}
+
+Methods
+-------
+
+{%- for item in members %}
+{%- if
+   not item.startswith('_')
+   and item not in inherited_members
+   and item not in attributes
+   %}
+
+{{ item | underline("~") }}
+
+.. container:: py attribute
+
+   .. automethod:: {{[fullname, item] | join('.')}}
+
+{%- endif %}
+{%- endfor %}
+{%- endif %}
+
+
+{%- if name in ["StreamingMediaDecoder", "StreamingMediaEncoder"] %}
+
+Support Structures
+------------------
+
+{%- if name == "StreamingMediaDecoder" %}
+{%- for item in [
+    "ChunkTensor",
+    "SourceStream",
+    "SourceAudioStream",
+    "SourceVideoStream",
+    "OutputStream",
+    "OutputAudioStream",
+    "OutputVideoStream",
+] %}
+
+{{ item | underline("~") }}
+
+.. autoclass:: torio.io._streaming_media_decoder::{{item}}()
+   :members:
+
+{%- endfor %}
+
+{%- elif name == "StreamingMediaEncoder" %}
+
+CodecConfig
+~~~~~~~~~~~
+
+.. autoclass:: torio.io::CodecConfig
+   :members:
+
+{%- endif %}
+{%- endif %}

docs/source/conf.py

@@ -385,13 +385,6 @@ def inject_minigalleries(app, what, name, obj, options, lines):
 def setup(app):
     app.connect("autodoc-process-docstring", inject_minigalleries)
 
-    from torchaudio.io import StreamReader, StreamWriter
-
-    # need to assign the names here, otherwise autodoc won't document these classes,
-    # and will instead just say 'alias of ...'
-    StreamReader.__name__ = "StreamReader"
-    StreamWriter.__name__ = "StreamWriter"
-
 
 from custom_directives import CustomCardEnd, CustomCardItem, CustomCardStart, SupportedDevices, SupportedProperties
 

docs/source/index.rst

@@ -108,6 +108,14 @@ model implementations and application components.
    kaldi_io
    utils
 
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   torio
+   torio.io
+   torio.utils
+
 .. toctree::
    :maxdepth: 1
    :caption: Python Prototype API Reference
@@ -364,15 +372,30 @@ Citing torchaudio
 
 If you find torchaudio useful, please cite the following paper:
 
+-  Hwang, J., Hira, M., Chen, C., Zhang, X., Ni, Z., Sun, G., Ma, P., Huang, R., Pratap, V.,
+   Zhang, Y., Kumar, A., Yu, C.-Y., Zhu, C., Liu, C., Kahn, J., Ravanelli, M., Sun, P.,
+   Watanabe, S., Shi, Y., Tao, T., Scheibler, R., Cornell, S., Kim, S., & Petridis, S. (2023).
+   TorchAudio 2.1: Advancing speech recognition, self-supervised learning, and audio processing components for PyTorch. arXiv preprint arXiv:2310.17864
+
 - Yang, Y.-Y., Hira, M., Ni, Z., Chourdia, A., Astafurov, A., Chen, C., Yeh, C.-F., Puhrsch, C.,
   Pollack, D., Genzel, D., Greenberg, D., Yang, E. Z., Lian, J., Mahadeokar, J., Hwang, J.,
   Chen, J., Goldsborough, P., Roy, P., Narenthiran, S., Watanabe, S., Chintala, S.,
   Quenneville-Bélair, V, & Shi, Y. (2021).
   TorchAudio: Building Blocks for Audio and Speech Processing. arXiv preprint arXiv:2110.15018.
 
-
 In BibTeX format:
 
+.. code-block:: bibtex
+
+   @misc{hwang2023torchaudio,
+      title={TorchAudio 2.1: Advancing speech recognition, self-supervised learning, and audio processing components for PyTorch}, 
+      author={Jeff Hwang and Moto Hira and Caroline Chen and Xiaohui Zhang and Zhaoheng Ni and Guangzhi Sun and Pingchuan Ma and Ruizhe Huang and Vineel Pratap and Yuekai Zhang and Anurag Kumar and Chin-Yun Yu and Chuang Zhu and Chunxi Liu and Jacob Kahn and Mirco Ravanelli and Peng Sun and Shinji Watanabe and Yangyang Shi and Yumeng Tao and Robin Scheibler and Samuele Cornell and Sean Kim and Stavros Petridis},
+      year={2023},
+      eprint={2310.17864},
+      archivePrefix={arXiv},
+      primaryClass={eess.AS}
+   }
+
 .. code-block:: bibtex
 
     @article{yang2021torchaudio,
@@ -388,14 +411,3 @@ In BibTeX format:
       journal={arXiv preprint arXiv:2110.15018},
       year={2021}
     }
-
-.. code-block:: bibtex
-
-   @misc{hwang2023torchaudio,
-      title={TorchAudio 2.1: Advancing speech recognition, self-supervised learning, and audio processing components for PyTorch}, 
-      author={Jeff Hwang and Moto Hira and Caroline Chen and Xiaohui Zhang and Zhaoheng Ni and Guangzhi Sun and Pingchuan Ma and Ruizhe Huang and Vineel Pratap and Yuekai Zhang and Anurag Kumar and Chin-Yun Yu and Chuang Zhu and Chunxi Liu and Jacob Kahn and Mirco Ravanelli and Peng Sun and Shinji Watanabe and Yangyang Shi and Yumeng Tao and Robin Scheibler and Samuele Cornell and Sean Kim and Stavros Petridis},
-      year={2023},
-      eprint={2310.17864},
-      archivePrefix={arXiv},
-      primaryClass={eess.AS}
-   }

docs/source/installation.rst

@@ -48,13 +48,13 @@ Optional Dependencies
   compatible FFmpeg libraries.
 
   If you need to specify the version of FFmpeg TorchAudio searches and links, you can
-  specify it via the environment variable ``TORCHAUDIO_USE_FFMPEG_VERSION``. For example,
-  by setting ``TORCHAUDIO_USE_FFMPEG_VERSION=5``, TorchAudio will only look for FFmpeg
+  specify it via the environment variable ``TORIO_USE_FFMPEG_VERSION``. For example,
+  by setting ``TORIO_USE_FFMPEG_VERSION=5``, TorchAudio will only look for FFmpeg
   5.
 
   If for some reason, this search mechanism is causing an issue, you can disable
   the FFmpeg integration entirely by setting the environment variable
-  ``TORCHAUDIO_USE_FFMPEG=0``.
+  ``TORIO_USE_FFMPEG=0``.
 
   There are multiple ways to install FFmpeg libraries.
   If you are using Anaconda Python distribution,

docs/source/torio.io.rst

+.. py:module:: torio.io
+
+torio.io
+========
+
+.. currentmodule:: torio.io
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: autosummary/torio_io_class.rst
+
+   StreamingMediaDecoder
+   StreamingMediaEncoder
+
+.. rubric:: Tutorials using ``torio.io``
+
+.. minigallery:: torio.io
+
+.. minigallery:: torchaudio.io

docs/source/torio.rst

+.. py:module:: torio
+
+torio
+=====
+
+.. currentmodule:: torio.io
+
+``torio`` is an alternative top-level module for I/O features. It is the extraction of the core implementation of I/O feature of ``torchaudio``.
+
+If you want to use the multimedia processing features, but do not want to depend on the entire ``torchaudio`` package, you can use ``torio``.
+
+.. note::
+
+   Currently, ``torio`` is distributed alongside ``torchaudio``, and there is no stand-alone
+   procedure to install ``torio`` only. Please refer to https://pytorch.org/get-started/locally/
+   for the installation of ``torchaudio``.

docs/source/torio.utils.rst

+.. py:module:: torio.utils
+
+torio.utils
+===========
+
+``torio.utils`` module contains utility functions to query and configure the global state of third party libraries.
+
+.. currentmodule:: torio.utils
+
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: autosummary/utils.rst
+
+   ffmpeg_utils