Add C++ documentation (#2994)

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

.circleci/config.yml

@@ -842,8 +842,8 @@ jobs:
             fi
             conda install -v -y -c file://$HOME/workspace/conda-bld torchaudio
             # gxx_linux-64 is for installing pesq library that depends on cython
-            conda install -y pandoc 'ffmpeg<5' gxx_linux-64
-            apt update -qq && apt-get -qq install -y git make
+            conda install -y pandoc 'ffmpeg<5' gxx_linux-64 git make
+            conda install -y -c conda-forge doxygen
             pip install --progress-bar off -r docs/requirements.txt -r docs/requirements-tutorials.txt
       - run:
           name: Build docs

.circleci/config.yml.in

@@ -842,8 +842,8 @@ jobs:
             fi
             conda install -v -y -c file://$HOME/workspace/conda-bld torchaudio
             # gxx_linux-64 is for installing pesq library that depends on cython
-            conda install -y pandoc 'ffmpeg<5' gxx_linux-64
-            apt update -qq && apt-get -qq install -y git make
+            conda install -y pandoc 'ffmpeg<5' gxx_linux-64 git make
+            conda install -y -c conda-forge doxygen
             pip install --progress-bar off -r docs/requirements.txt -r docs/requirements-tutorials.txt
       - run:
           name: Build docs

.gitignore

@@ -69,6 +69,7 @@ instance/
 # Sphinx documentation
 docs/_build/
 docs/src/
+docs/source/cpp
 docs/source/tutorials
 docs/source/gen_images
 docs/source/gen_modules

docs/Makefile

@@ -24,4 +24,11 @@ docset: html
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	doxygen source/Doxyfile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf $(SOURCEDIR)/generated/
+	rm -rf $(SOURCEDIR)/aen_images/
+	rm -rf $(SOURCEDIR)/gen_modules/

docs/requirements.txt

@@ -2,6 +2,9 @@ Jinja2<3.1.0
 matplotlib
 pyparsing<3,>=2.0.2
 
+# C++ docs
+breathe==4.34.0
+
 # Note:
 # When changing Sphinx-related packages, make sure that the custom behaviors in the following
 # locations are working as expected.

docs/source/_static/css/custom.css

@@ -55,3 +55,23 @@ article.pytorch-article div.tutorials-card div.card-body code {
     border-bottom: none;
     background-color: #AFB8C133;
 }
+/* C++ doc */
+/* Fix the malindentation of `class` header*/
+article.pytorch-article .cpp.class dt {
+    padding-left: 0.5em;
+}
+/* keywords like const and explicit, class */
+dt.sig.sig-object.cpp > span.k > span.pre {
+    color: #c95362;
+}
+
+dt.sig.sig-object.cpp > span.n:not(.sig-param) > span.pre {
+    color: #9257c6;
+}
+/* Fix */
+dt.sig.sig-object.cpp > span.sig-prename.descclassname > span.n > span.pre {
+    color: #6c6c6d;
+}
+dt.sig.sig-object.cpp > span.sig-prename.descname > span.n > span.pre {
+    color: #6c6c6d;
+}

docs/source/_templates/autosummary/io_class.rst

@@ -17,12 +17,12 @@
 {%- if attributes %}
 
 Properties
-==========
+----------
 
 {%- for item in attributes %}
 {%- if not item.startswith('_') and item not in inherited_members %}
 
-{{ item | underline("-") }}
+{{ item | underline("~") }}
 
 .. container:: py attribute
 
@@ -33,12 +33,12 @@ Properties
 {%- endif %}
 
 Methods
-=======
+-------
 
 {%- for item in members %}
 {%- if not item.startswith('_') and item not in inherited_members and item not in attributes %}
 
-{{ item | underline("-") }}
+{{ item | underline("~") }}
 
 .. container:: py attribute
 
@@ -50,7 +50,7 @@ Methods
 {%- if name == "StreamReader" %}
 
 Support Structures
-==================
+------------------
 
 {%- for item in [
     "ChunkTensor",
@@ -60,7 +60,7 @@ Support Structures
     "OutputStream",
 ] %}
 
-{{ item | underline("-") }}
+{{ item | underline("~") }}
 
 .. autoclass:: torchaudio.io._stream_reader.{{item}}()
    :members:

docs/source/_templates/layout.html

@@ -83,7 +83,6 @@
           $(".main-menu a:contains('Github')").each(overwrite);
       });
 
-      {% if 'tutorial' in pagename %}
       {#
        # Override the right side menu bar behavior so that subsections
        # are shown by default in tutorial page.
@@ -107,6 +106,30 @@
                }
            };
        });
-      {% endif %}
     </script>
+
+    {% if 'libtorchaudio' in pagename %}
+    {#
+     # change the layout of signature one param per line if #params >= 2
+     #}
+    <script type="text/javascript">
+      $(window).ready(function() {
+          $("dt.sig.sig-object.cpp").each(function(i) {
+              let newline = "<br>\20\20\20\20";
+              let params = $(this).children(".sig-param");
+              if (params.length >= 2) {
+                  $(this).html($(this).html().replace(/, /g, "," + newline));
+                  $(this).children(".sig-paren").each(function(i) {
+                      console.log(i, $(this));
+                      if (i == 0) {
+                          $(this).html($(this).html() + newline + "\20");
+                      } else if (i == 1) {
+                          $(this).html("<br>" + $(this).html());
+                      }
+                  });
+              }
+          });
+      });
+    </script>
+    {% endif %}
 {% endblock %}

docs/source/conf.py

@@ -52,8 +52,20 @@ extensions = [
     "sphinxcontrib.bibtex",
     "sphinx_gallery.gen_gallery",
     "nbsphinx",
+    "breathe",
 ]
 
+breathe_projects = {"libtorchaudio": "cpp/xml"}
+
+breathe_default_project = "libtorchaudio"
+
+breathe_projects_source = {
+    "libtorchaudio": (
+        "../../torchaudio/csrc/ffmpeg/",
+        ["ffmpeg.h"],
+    )
+}
+
 nbsphinx_requirejs_path = ""
 
 autodoc_member_order = "bysource"

docs/source/index.rst

@@ -72,7 +72,7 @@ model implementations and application components.
 
 .. toctree::
    :maxdepth: 1
-   :caption: API Reference
+   :caption: Python API Reference
    :hidden:
 
    torchaudio
@@ -91,7 +91,7 @@ model implementations and application components.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Prototype API Reference
+   :caption: Python Prototype API Reference
    :hidden:
 
    prototype
@@ -101,6 +101,15 @@ model implementations and application components.
    prototype.pipelines
    prototype.transforms
 
+.. toctree::
+   :maxdepth: 1
+   :caption: C++ Prototype API Reference
+   :hidden:
+
+   libtorchaudio
+   libtorchaudio.stream_reader
+   libtorchaudio.stream_writer
+
 .. toctree::
    :maxdepth: 1
    :caption: PyTorch Libraries

docs/source/libtorchaudio.rst

+libtorchaudio
+=============
+
+.. warning::
+   TorchAudio's C++ API is a prototype feature.
+   API/ABI backward compatibility is not guaranteed.
+
+.. toctree::
+   libtorchaudio.stream_reader
+   libtorchaudio.stream_writer

docs/source/libtorchaudio.stream_reader.rst

+.. warning::
+   TorchAudio's C++ API is a prototype feature.
+   API/ABI backward compatibility is not guaranteed.
+
+torchaudio::io::StreamReader
+============================
+
+.. doxygenclass:: torchaudio::io::StreamReader
+
+Constructors
+------------
+
+.. doxygenfunction:: torchaudio::io::StreamReader::StreamReader(const std::string &src, const c10::optional<std::string> &format = {}, const c10::optional<OptionDict> &option = {})
+
+Query Methods
+-------------
+
+find_best_audio_stream
+^^^^^^^^^^^^^^^^^^^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::find_best_audio_stream
+
+find_best_video_stream
+^^^^^^^^^^^^^^^^^^^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::find_best_video_stream
+
+get_metadata
+^^^^^^^^^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::get_metadata
+
+num_src_streams
+^^^^^^^^^^^^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::num_src_streams
+
+get_src_stream_info
+^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamReader::get_src_stream_info
+
+num_out_streams
+^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamReader::num_out_streams
+
+get_out_stream_info
+^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamReader::get_out_stream_info
+
+is_buffer_ready
+^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamReader::is_buffer_ready
+
+Configure Methods
+-----------------
+
+add_audio_stream
+^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamReader::add_audio_stream
+
+add_video_stream
+^^^^^^^^^^^^^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::add_video_stream
+
+remove_stream
+^^^^^^^^^^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::remove_stream
+
+Stream Methods
+^^^^^^^^^^^^^^
+
+seek
+^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::seek
+
+process_packet
+^^^^^^^^^^^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::process_packet
+
+process_packet_block
+^^^^^^^^^^^^^^^^^^^^
+.. doxygenfunction:: torchaudio::io::StreamReader::process_packet_block
+
+Retrieval Methods
+-----------------
+
+pop_chunks
+^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamReader::pop_chunks
+
+
+Support Structures
+------------------
+
+Chunk
+^^^^^
+
+.. container:: py attribute
+
+   .. doxygenstruct:: torchaudio::io::Chunk
+      :members:
+
+SrcStreaminfo
+^^^^^^^^^^^^^
+
+.. container:: py attribute
+
+   .. doxygenstruct:: torchaudio::io::SrcStreamInfo
+      :members:
+
+OutputStreaminfo
+^^^^^^^^^^^^^^^^
+
+.. container:: py attribute
+
+   .. doxygenstruct:: torchaudio::io::OutputStreamInfo
+      :members:

docs/source/libtorchaudio.stream_writer.rst

+.. warning::
+   TorchAudio's C++ API is prototype feature.
+   API/ABI backward compatibility is not guaranteed.
+
+torchaudio::io::StreamWriter
+============================
+
+.. doxygenclass:: torchaudio::io::StreamWriter
+
+Constructors
+------------
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::StreamWriter(const std::string &dst, const c10::optional<std::string> &format = {})
+
+Config methods
+--------------
+
+add_audio_stream
+^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::add_audio_stream
+
+add_video_stream
+^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::add_video_stream
+
+set_metadata
+^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::set_metadata
+
+Write methods
+-------------
+
+open
+^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::open
+
+close
+^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::close
+
+write_audio_chunk
+^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::write_audio_chunk
+
+write_video_chunk
+^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::write_video_chunk
+
+flush
+^^^^^
+
+.. doxygenfunction:: torchaudio::io::StreamWriter::flush

torchaudio/csrc/ffmpeg/ffmpeg.h

@@ -22,6 +22,8 @@ extern "C" {
 #include <libavutil/pixdesc.h>
 }
 
+/// @cond
+
 namespace torchaudio {
 namespace io {
 
@@ -189,3 +191,5 @@ struct AVFilterGraphPtr : public Wrapper<AVFilterGraph, AVFilterGraphDeleter> {
 };
 } // namespace io
 } // namespace torchaudio
+
+/// @endcond

torchaudio/csrc/ffmpeg/stream_reader/stream_reader.h

@@ -38,14 +38,18 @@ class StreamReader {
   ///
   ///@{
 
+  /// @cond
+
   /// Construct StreamReader from already initialized AVFormatContext.
   /// This is a low level constructor interact with FFmpeg directly.
   /// One can provide custom AVFormatContext in case the other constructor
   /// does not meet a requirement.
-  /// @param AVFormatContext An initialized AVFormatContext. StreamReader will
+  /// @param pFormatContext An initialized AVFormatContext. StreamReader will
   /// own the resources and release it at the end.
   explicit StreamReader(AVFormatContext* pFormatContext);
 
+  /// @endcond
+
   /// Construct media processor from soruce URI.
   ///
   /// @param src URL of source media, in the format FFmpeg can understand.
@@ -58,6 +62,8 @@ class StreamReader {
       const c10::optional<std::string>& format = {},
       const c10::optional<OptionDict>& option = {});
 
+  /// @cond
+
   /// Concstruct media processor from custom IO.
   ///
   /// @param io_ctx Custom IO Context.
@@ -70,8 +76,12 @@ class StreamReader {
       const c10::optional<std::string>& format = {},
       const c10::optional<OptionDict>& option = {});
 
+  /// @endcond
+
   ///@}
 
+  /// @cond
+
   ~StreamReader() = default;
   // Non-copyable
   StreamReader(const StreamReader&) = delete;
@@ -80,6 +90,8 @@ class StreamReader {
   StreamReader(StreamReader&&) = default;
   StreamReader& operator=(StreamReader&&) = default;
 
+  /// @endcond
+
   //////////////////////////////////////////////////////////////////////////////
   // Helper methods
   //////////////////////////////////////////////////////////////////////////////
@@ -118,8 +130,6 @@ class StreamReader {
   /// The valid value range is ``[0, num_src_streams())``.
   SrcStreamInfo get_src_stream_info(int i) const;
   /// Fetch the number of output streams defined by client code.
-  ///
-  /// @addtogroup stream_reader_query_methods
   int64_t num_out_streams() const;
   /// Fetch information about the specified output stream.
   ///

torchaudio/csrc/ffmpeg/stream_reader/typedefs.h

@@ -6,6 +6,7 @@
 namespace torchaudio {
 namespace io {
 
+/// Information about source stream found in the input media.
 struct SrcStreamInfo {
   /// @name COMMON MEMBERS
   ///@{
@@ -96,6 +97,7 @@ struct SrcStreamInfo {
   ///@}
 };
 
+/// Information about output stream configured by user code
 struct OutputStreamInfo {
   /// The index of the input source stream
   int source_index;

torchaudio/csrc/ffmpeg/stream_writer/stream_writer.h

@@ -7,6 +7,8 @@
 namespace torchaudio {
 namespace io {
 
+/// @cond
+
 struct OutputStream {
   AVStream* stream;
   AVCodecContextPtr codec_ctx;
@@ -22,6 +24,8 @@ struct OutputStream {
   AVBufferRefPtr hw_frame_ctx;
 };
 
+/// @endcond
+
 ///
 /// Encode and write audio/video streams chunk by chunk
 ///
@@ -32,8 +36,12 @@ class StreamWriter {
   AVPacketPtr pkt;
 
  protected:
+  /// @cond
+
   explicit StreamWriter(AVFormatContext*);
 
+  /// @endcond
+
  public:
   /// Construct StreamWriter from destination URI
   ///
@@ -44,6 +52,8 @@ class StreamWriter {
       const std::string& dst,
       const c10::optional<std::string>& format = {});
 
+  /// @cond
+
   /// Construct StreamWriter from custom IO
   ///
   /// @param io_ctx Custom IO.
@@ -53,6 +63,8 @@ class StreamWriter {
       AVIOContext* io_ctx,
       const c10::optional<std::string>& format);
 
+  /// @endcond
+
   // Non-copyable
   StreamWriter(const StreamWriter&) = delete;
   StreamWriter& operator=(const StreamWriter&) = delete;
@@ -61,12 +73,12 @@ class StreamWriter {
   // Query methods
   //////////////////////////////////////////////////////////////////////////////
  public:
-  /// @internal
+  /// @cond
 
   /// Print the configured outputs
   void dump_format(int64_t i);
 
-  /// @endinternal
+  /// @endcond
 
   //////////////////////////////////////////////////////////////////////////////
   // Configure methods