Adopt `:autosummary:` in `torchaudio.io` module doc (#2681)

Summary:
This commit adopts :autosummary: directive to `torchaudio.io` module.
It adds table of contents on `torchaudio.io` level.

https://output.circle-artifacts.com/output/job/282089d1-c120-4d22-809f-0e0ac0947c37/artifacts/0/docs/io.html
<img width="1094" alt="Screen Shot 2022-09-16 at 7 33 32 AM" src="https://user-images.githubusercontent.com/855818/190520248-27e469f8-7689-4dc2-b591-7b3f08bb4dff.png">

https://output.circle-artifacts.com/output/job/282089d1-c120-4d22-809f-0e0ac0947c37/artifacts/0/docs/generated/torchaudio.io.StreamReader.html#torchaudio.io.StreamReader
<img width="1108" alt="Screen Shot 2022-09-16 at 7 33 59 AM" src="https://user-images.githubusercontent.com/855818/190520292-d090fed0-2f18-4961-b9f3-9e4808fd437e.png">

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

Reviewed By: carolineechen

Differential Revision: D39560459

Pulled By: mthrok

fbshipit-source-id: 3de5f22b8d8d0834dfd8bac8619fbfaa44c5f4dd

.gitignore

@@ -72,6 +72,7 @@ docs/src/
 docs/source/tutorials
 docs/source/gen_images
 docs/source/gen_modules
+docs/source/generated
 
 # PyBuilder
 target/

docs/source/_static/css/custom.css

@@ -23,3 +23,6 @@ article.pytorch-article .sphx-glr-thumbnails .sphx-glr-thumbcontainer {
     margin-right: 0;
     margin-left: 0;
 }
+article.pytorch-article div.section div.wy-table-responsive tbody td {
+    width: 50%;
+}

docs/source/_templates/autosummary/io_class.rst

+..
+  autogenerated from source/_templates/autosummary/io_class.rst
+
+{#-
+    ################################################################################
+    # autosummary template for torchaudio.io module
+    # Since StreamReader/StreamWriter 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 %}
+
+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 %}
+
+{%- if name == "StreamReader" %}
+
+Support Structures
+==================
+
+{%- for item in ["StreamReaderSourceStream", "StreamReaderSourceAudioStream", "StreamReaderSourceVideoStream", "StreamReaderOutputStream"] %}
+
+{{ item | underline("-") }}
+
+.. autoclass:: torchaudio.io.{{item}}()
+   :members:
+
+{%- endfor %}
+{%- endif %}

docs/source/io.rst

@@ -3,40 +3,14 @@ torchaudio.io
 
 .. currentmodule:: torchaudio.io
 
+.. autosummary::
+   :toctree: generated
+   :nosignatures:
+   :template: autosummary/io_class.rst
 
-StreamReader
-------------
+   StreamReader
+   StreamWriter
 
-.. autoclass:: StreamReader
-  :members:
+.. rubric:: Tutorials using Streaming API
 
-StreamReaderSourceStream
-------------------------
-
-.. autoclass:: StreamReaderSourceStream
-  :members:
-
-StreamReaderSourceAudioStream
------------------------------
-
-.. autoclass:: StreamReaderSourceAudioStream
-  :members:
-
-StreamReaderSourceVideoStream
------------------------------
-
-.. autoclass:: StreamReaderSourceVideoStream
-  :members:
-
-StreamReaderOutputStream
-------------------------
-
-.. autoclass:: StreamReaderOutputStream
-  :members:
-
-
-StreamWriter
-------------
-
-.. autoclass:: StreamWriter
-  :members:
+.. minigallery:: torchaudio.io.StreamReader torchaudio.io.StreamWriter

torchaudio/io/_stream_reader.py

@@ -9,24 +9,23 @@ import torchaudio
 
 @dataclass
 class StreamReaderSourceStream:
-    """StreamReaderSourceStream()
+    """The metadata of a source stream, returned by :meth:`~torchaudio.io.StreamReader.get_src_stream_info`.
 
-    The metadata of a source stream. This class is used when representing streams of
-    media type other than `audio` or `video`.
+    This class is used when representing streams of media type other than `audio` or `video`.
 
-    When source stream is `audio` or `video` type, :py:class:`SourceAudioStream` and
-    :py:class:`SourceVideoStream`, which reports additional media-specific attributes,
+    When source stream is `audio` or `video` type, :class:`StreamReaderSourceAudioStream` and
+    :class:`StreamReaderSourceVideoStream`, which reports additional media-specific attributes,
     are used respectively.
     """
 
     media_type: str
     """The type of the stream.
-    One of `audio`, `video`, `data`, `subtitle`, `attachment` and empty string.
+    One of ``"audio"``, ``"video"``, ``"data"``, ``"subtitle"``, ``"attachment"`` and empty string.
 
     .. note::
-       Only `audio` and `video` streams are supported for output.
+       Only audio and video streams are supported for output.
     .. note::
-       Still images, such as PNG and JPEG formats are reported as `video`.
+       Still images, such as PNG and JPEG formats are reported as video.
     """
     codec: str
     """Short name of the codec. Such as ``"pcm_s16le"`` and ``"h264"``."""
@@ -67,13 +66,12 @@ class StreamReaderSourceStream:
 
 @dataclass
 class StreamReaderSourceAudioStream(StreamReaderSourceStream):
-    """StreamReaderSourceAudioStream()
+    """The metadata of an audio source stream, returned by :meth:`~torchaudio.io.StreamReader.get_src_stream_info`.
 
-    The metadata of an audio source stream.
+    This class is used when representing audio stream.
 
-    In addition to the attributes reported by :py:func:`StreamReaderSourceStream`,
-    when the source stream is audio type, then the following additional attributes
-    are reported.
+    In addition to the attributes reported by :class:`StreamReaderSourceStream`,
+    the following attributes are reported.
     """
 
     sample_rate: float
@@ -84,13 +82,12 @@ class StreamReaderSourceAudioStream(StreamReaderSourceStream):
 
 @dataclass
 class StreamReaderSourceVideoStream(StreamReaderSourceStream):
-    """StreamReaderSourceVideoStream()
+    """The metadata of a video source stream, returned by :meth:`~torchaudio.io.StreamReader.get_src_stream_info`.
 
-    The metadata of a video source stream.
+    This class is used when representing video stream.
 
-    In addition to the attributes reported by :py:func:`StreamReaderSourceStream`,
-    when the source stream is audio type, then the following additional attributes
-    are reported.
+    In addition to the attributes reported by :class:`StreamReaderSourceStream`,
+    the following attributes are reported.
     """
 
     width: int
@@ -170,9 +167,8 @@ def _parse_si(i):
 
 @dataclass
 class StreamReaderOutputStream:
-    """OutputStream()
-
-    Output stream configured on :py:class:`StreamReader`.
+    """Output stream configured on :class:`StreamReader`,
+    returned by :meth:`~torchaudio.io.StreamReader.get_out_stream_info`.
     """
 
     source_index: int