Skip to content

Commit 258169e

Browse files
mthrokmthrok
authored
Update doc (#3677)
* Update doc * Update citation
1 parent 6518fa9 commit 258169e

File tree

8 files changed

+170
-55
lines changed

8 files changed

+170
-55
lines changed

‎docs/source/_templates/autosummary/io_class.rst‎

Lines changed: 2 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@
1414

1515
.. autoclass:: {{ fullname }}
1616

17+
{%- if name not in ["StreamReader", "StreamWriter"] %}
18+
1719
{%- if attributes %}
1820

1921
Properties
@@ -54,37 +56,4 @@ Methods
5456
{%- endfor %}
5557
{%- endif %}
5658

57-
58-
{%- if name in ["StreamReader", "StreamWriter"] %}
59-
60-
Support Structures
61-
------------------
62-
63-
{%- if name == "StreamReader" %}
64-
{%- for item in [
65-
"ChunkTensor",
66-
"SourceStream",
67-
"SourceAudioStream",
68-
"SourceVideoStream",
69-
"OutputStream",
70-
"OutputAudioStream",
71-
"OutputVideoStream",
72-
] %}
73-
74-
{{ item | underline("~") }}
75-
76-
.. autoclass:: torio.io._streaming_media_decoder.{{item}}()
77-
:members:
78-
79-
{%- endfor %}
80-
81-
{%- elif name == "StreamWriter" %}
82-
83-
CodecConfig
84-
~~~~~~~~~~~
85-
86-
.. autoclass:: torchaudio.io::CodecConfig
87-
:members:
88-
89-
{%- endif %}
9059
{%- endif %}

‎docs/source/_templates/autosummary/torio_io_class.rst‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
..
2+
autogenerated from source/_templates/autosummary/torio_io_class.rst
3+
4+
{#-
5+
################################################################################
6+
# autosummary template for torio.io module
7+
# Since StreamingMediaDecoder/StreamingMediaEncoder have many methods/properties,
8+
# we want to list them up in the table of contents.
9+
# The default class template does not do this, so we use custom one here.
10+
################################################################################
11+
#}
12+
13+
{{ name | underline }}
14+
15+
.. autoclass:: {{ fullname }}
16+
17+
{%- if attributes %}
18+
19+
Properties
20+
----------
21+
22+
{%- for item in attributes %}
23+
{%- if not item.startswith('_') and item not in inherited_members %}
24+
25+
{{ item | underline("~") }}
26+
27+
.. container:: py attribute
28+
29+
.. autoproperty:: {{[fullname, item] | join('.')}}
30+
31+
{%- endif %}
32+
{%- endfor %}
33+
{%- endif %}
34+
35+
{%- if members %}
36+
37+
Methods
38+
-------
39+
40+
{%- for item in members %}
41+
{%- if
42+
not item.startswith('_')
43+
and item not in inherited_members
44+
and item not in attributes
45+
%}
46+
47+
{{ item | underline("~") }}
48+
49+
.. container:: py attribute
50+
51+
.. automethod:: {{[fullname, item] | join('.')}}
52+
53+
{%- endif %}
54+
{%- endfor %}
55+
{%- endif %}
56+
57+
58+
{%- if name in ["StreamingMediaDecoder", "StreamingMediaEncoder"] %}
59+
60+
Support Structures
61+
------------------
62+
63+
{%- if name == "StreamingMediaDecoder" %}
64+
{%- for item in [
65+
"ChunkTensor",
66+
"SourceStream",
67+
"SourceAudioStream",
68+
"SourceVideoStream",
69+
"OutputStream",
70+
"OutputAudioStream",
71+
"OutputVideoStream",
72+
] %}
73+
74+
{{ item | underline("~") }}
75+
76+
.. autoclass:: torio.io._streaming_media_decoder::{{item}}()
77+
:members:
78+
79+
{%- endfor %}
80+
81+
{%- elif name == "StreamingMediaEncoder" %}
82+
83+
CodecConfig
84+
~~~~~~~~~~~
85+
86+
.. autoclass:: torio.io::CodecConfig
87+
:members:
88+
89+
{%- endif %}
90+
{%- endif %}

‎docs/source/conf.py‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -385,13 +385,6 @@ def inject_minigalleries(app, what, name, obj, options, lines):
385385
def setup(app):
386386
app.connect("autodoc-process-docstring", inject_minigalleries)
387387

388-
from torchaudio.io import StreamReader, StreamWriter
389-
390-
# need to assign the names here, otherwise autodoc won't document these classes,
391-
# and will instead just say 'alias of ...'
392-
StreamReader.__name__ = "StreamReader"
393-
StreamWriter.__name__ = "StreamWriter"
394-
395388

396389
from custom_directives import CustomCardEnd, CustomCardItem, CustomCardStart, SupportedDevices, SupportedProperties
397390

‎docs/source/index.rst‎

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,14 @@ model implementations and application components.
108108
kaldi_io
109109
utils
110110

111+
.. toctree::
112+
:maxdepth: 1
113+
:hidden:
114+
115+
torio
116+
torio.io
117+
torio.utils
118+
111119
.. toctree::
112120
:maxdepth: 1
113121
:caption: Python Prototype API Reference
@@ -364,15 +372,30 @@ Citing torchaudio
364372

365373
If you find torchaudio useful, please cite the following paper:
366374

375+
- Hwang, J., Hira, M., Chen, C., Zhang, X., Ni, Z., Sun, G., Ma, P., Huang, R., Pratap, V.,
376+
Zhang, Y., Kumar, A., Yu, C.-Y., Zhu, C., Liu, C., Kahn, J., Ravanelli, M., Sun, P.,
377+
Watanabe, S., Shi, Y., Tao, T., Scheibler, R., Cornell, S., Kim, S., & Petridis, S. (2023).
378+
TorchAudio 2.1: Advancing speech recognition, self-supervised learning, and audio processing components for PyTorch. arXiv preprint arXiv:2310.17864
379+
367380
- Yang, Y.-Y., Hira, M., Ni, Z., Chourdia, A., Astafurov, A., Chen, C., Yeh, C.-F., Puhrsch, C.,
368381
Pollack, D., Genzel, D., Greenberg, D., Yang, E. Z., Lian, J., Mahadeokar, J., Hwang, J.,
369382
Chen, J., Goldsborough, P., Roy, P., Narenthiran, S., Watanabe, S., Chintala, S.,
370383
Quenneville-Bélair, V, & Shi, Y. (2021).
371384
TorchAudio: Building Blocks for Audio and Speech Processing. arXiv preprint arXiv:2110.15018.
372385

373-
374386
In BibTeX format:
375387

388+
.. code-block:: bibtex
389+
390+
@misc{hwang2023torchaudio,
391+
title={TorchAudio 2.1: Advancing speech recognition, self-supervised learning, and audio processing components for PyTorch},
392+
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},
393+
year={2023},
394+
eprint={2310.17864},
395+
archivePrefix={arXiv},
396+
primaryClass={eess.AS}
397+
}
398+
376399
.. code-block:: bibtex
377400
378401
@article{yang2021torchaudio,
@@ -388,14 +411,3 @@ In BibTeX format:
388411
journal={arXiv preprint arXiv:2110.15018},
389412
year={2021}
390413
}
391-
392-
.. code-block:: bibtex
393-
394-
@misc{hwang2023torchaudio,
395-
title={TorchAudio 2.1: Advancing speech recognition, self-supervised learning, and audio processing components for PyTorch},
396-
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},
397-
year={2023},
398-
eprint={2310.17864},
399-
archivePrefix={arXiv},
400-
primaryClass={eess.AS}
401-
}

‎docs/source/installation.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,13 +48,13 @@ Optional Dependencies
4848
compatible FFmpeg libraries.
4949

5050
If you need to specify the version of FFmpeg TorchAudio searches and links, you can
51-
specify it via the environment variable ``TORCHAUDIO_USE_FFMPEG_VERSION``. For example,
52-
by setting ``TORCHAUDIO_USE_FFMPEG_VERSION=5``, TorchAudio will only look for FFmpeg
51+
specify it via the environment variable ``TORIO_USE_FFMPEG_VERSION``. For example,
52+
by setting ``TORIO_USE_FFMPEG_VERSION=5``, TorchAudio will only look for FFmpeg
5353
5.
5454

5555
If for some reason, this search mechanism is causing an issue, you can disable
5656
the FFmpeg integration entirely by setting the environment variable
57-
``TORCHAUDIO_USE_FFMPEG=0``.
57+
``TORIO_USE_FFMPEG=0``.
5858

5959
There are multiple ways to install FFmpeg libraries.
6060
If you are using Anaconda Python distribution,

‎docs/source/torio.io.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
.. py:module:: torio.io
2+
3+
torio.io
4+
========
5+
6+
.. currentmodule:: torio.io
7+
8+
.. autosummary::
9+
:toctree: generated
10+
:nosignatures:
11+
:template: autosummary/torio_io_class.rst
12+
13+
StreamingMediaDecoder
14+
StreamingMediaEncoder
15+
16+
.. rubric:: Tutorials using ``torio.io``
17+
18+
.. minigallery:: torio.io
19+
20+
.. minigallery:: torchaudio.io

‎docs/source/torio.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. py:module:: torio
2+
3+
torio
4+
=====
5+
6+
.. currentmodule:: torio.io
7+
8+
``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``.
9+
10+
If you want to use the multimedia processing features, but do not want to depend on the entire ``torchaudio`` package, you can use ``torio``.
11+
12+
.. note::
13+
14+
Currently, ``torio`` is distributed alongside ``torchaudio``, and there is no stand-alone
15+
procedure to install ``torio`` only. Please refer to https://pytorch.org/get-started/locally/
16+
for the installation of ``torchaudio``.

‎docs/source/torio.utils.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. py:module:: torio.utils
2+
3+
torio.utils
4+
===========
5+
6+
``torio.utils`` module contains utility functions to query and configure the global state of third party libraries.
7+
8+
.. currentmodule:: torio.utils
9+
10+
.. autosummary::
11+
:toctree: generated
12+
:nosignatures:
13+
:template: autosummary/utils.rst
14+
15+
ffmpeg_utils

0 commit comments

Comments
 (0)