Disable doxygen / breathe / exhale generation of C++ API docs (#80451)

Fixes #79992

This PR:
* Removes doxygen / breathe / exhale configuration from the Sphinx config in `source/conf.py` so it no longer runs
* Maintains the human-generated content describing API usage in the various .rst files
    * Exception: `library.rst` is removed, as its main purpose is linking to API docs
* Removes all links to the generated API docs from the human-generated content

The build is nearly instantaneous now and should be much less memory intensive as well.
Pull Request resolved: https://github.com/pytorch/pytorch/pull/80451
Approved by: https://github.com/suo

docs/cpp/source/conf.py

@@ -16,11 +16,13 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
+
+# NB: C++ API doc generation using doxygen / breathe / exhale is currently disabled
+# due to OOM errors in CI. See https://github.com/pytorch/pytorch/issues/79992
+
 import os
 # sys.path.insert(0, os.path.abspath('.'))
 
-import textwrap
-
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -32,8 +34,6 @@ needs_sphinx = '3.1.2'
 # ones.
 extensions = [
     'sphinx.ext.intersphinx',
-    'breathe',
-    'exhale'
 ]
 
 intersphinx_mapping = {
@@ -44,11 +44,6 @@ intersphinx_mapping = {
 # items are expected / should be trimmed by.
 # This file is {repo_root}/docs/cpp/source/conf.py
 this_file_dir = os.path.abspath(os.path.dirname(__file__))
-doxygen_xml_dir = os.path.join(
-    os.path.dirname(this_file_dir),  # {repo_root}/docs/cpp
-    'build',                         # {repo_root}/docs/cpp/build
-    'xml'                            # {repo_root}/docs/cpp/build/xml
-)
 repo_root = os.path.dirname(  # {repo_root}
     os.path.dirname(          # {repo_root}/docs
         os.path.dirname(      # {repo_root}/docs/cpp
@@ -57,48 +52,6 @@ repo_root = os.path.dirname(  # {repo_root}
     )
 )
 
-breathe_projects = {"PyTorch": doxygen_xml_dir}
-breathe_default_project = "PyTorch"
-
-# Setup the exhale extension
-exhale_args = {
-    ############################################################################
-    # These arguments are required.                                            #
-    ############################################################################
-    "containmentFolder": "./api",
-    "rootFileName": "library_root.rst",
-    "rootFileTitle": "Library API",
-    "doxygenStripFromPath": repo_root,
-    ############################################################################
-    # Suggested optional arguments.                                            #
-    ############################################################################
-    "createTreeView": True,
-    "exhaleExecutesDoxygen": True,
-    "exhaleUseDoxyfile": True,
-    "verboseBuild": True,
-    ############################################################################
-    # HTML Theme specific configurations.                                      #
-    ############################################################################
-    # Fix broken Sphinx RTD Theme 'Edit on GitHub' links
-    # Search for 'Edit on GitHub' on the FAQ:
-    #     http://exhale.readthedocs.io/en/latest/faq.html
-    "pageLevelConfigMeta": ":github_url: https://github.com/pytorch/pytorch",
-    ############################################################################
-    # Individual page layout example configuration.                            #
-    ############################################################################
-    # Example of adding contents directives on custom kinds with custom title
-    "contentsTitle": "Page Contents",
-    "kindsWithContentsDirectives": ["class", "file", "namespace", "struct"],
-    # Exclude PIMPL files from class hierarchy tree and namespace pages.
-    "listingExclude": [r".*Impl$"],
-    ############################################################################
-    # Main library page layout example configuration.                          #
-    ############################################################################
-    "afterTitleDescription": textwrap.dedent(u'''
-        Welcome to the developer reference for the PyTorch C++ API.
-    '''),
-}
-
 # Tell sphinx what the primary language being documented is.
 primary_domain = 'cpp'
 

docs/cpp/source/index.rst

@@ -42,8 +42,7 @@ look as follows:
   auto c = a + b.to(at::kInt);
 
 This ``Tensor`` class and all other symbols in ATen are found in the ``at::``
-namespace, documented
-`here <https://pytorch.org/cppdocs/api/namespace_at.html#namespace-at>`_.
+namespace.
 
 Autograd
 --------
@@ -92,18 +91,8 @@ frontend includes the following:
 
 See `this document <https://pytorch.org/cppdocs/frontend.html>`_ for a more
 detailed description of the C++ frontend. Relevant sections of the `torch::`
-namespace related to the C++ Frontend include `torch::nn
-<https://pytorch.org/cppdocs/api/namespace_torch__nn.html#namespace-torch-nn>`_,
-`torch::optim
-<https://pytorch.org/cppdocs/api/namespace_torch__optim.html#namespace-torch-optim>`_,
-`torch::data
-<https://pytorch.org/cppdocs/api/namespace_torch__data.html#namespace-torch-data>`_,
-`torch::serialize
-<https://pytorch.org/cppdocs/api/namespace_torch__serialize.html#namespace-torch-serialize>`_,
-`torch::jit
-<https://pytorch.org/cppdocs/api/namespace_torch__jit.html#namespace-torch-jit>`_
-and `torch::python
-<https://pytorch.org/cppdocs/api/namespace_torch__python.html#namespace-torch-python>`_.
+namespace related to the C++ Frontend include `torch::nn`,
+`torch::optim`, `torch::data`, `torch::serialize`, `torch::jit`, and `torch::python`.
 Examples of the C++ frontend can be found in `this repository
 <https://github.com/pytorch/examples/tree/master/cpp>`_ which is being
 expanded on a continuous and active basis.
@@ -136,8 +125,7 @@ about this by following `this
 <https://pytorch.org/tutorials/advanced/cpp_export.html>`_ link. The second
 API concerns itself with scenarios in which you would like to extend
 TorchScript with custom operators, which can similarly be serialized and
-invoked from C++ during inference. Lastly, the `torch::jit::compile
-<https://pytorch.org/cppdocs/api/function_namespacetorch_1_1jit_1a176d99fd5bf0233119a5f49c07a1d01d.html#exhale-function-namespacetorch-1-1jit-1a176d99fd5bf0233119a5f49c07a1d01d>`_
+invoked from C++ during inference. Lastly, the `torch::jit::compile`
 function may be used to access the TorchScript compiler directly from C++.
 
 C++ Extensions
@@ -161,7 +149,6 @@ Contents
 
    installing
    frontend
-   api/library_root
 
 .. toctree::
   :glob:
@@ -170,13 +157,6 @@ Contents
 
   notes/*
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
 Acknowledgements
 ----------------
 

docs/cpp/source/library.rst

@@ -1,37 +0,0 @@
-Torch Library API
-=================
-
-The PyTorch C++ API provides capabilities for extending PyTorch's core library
-of operators with user defined operators and data types.  Extensions implemented
-using the Torch Library API are made available for use in both the PyTorch eager
-API as well as in TorchScript.
-
-For a tutorial style introduction to the library API, check out the
-`Extending TorchScript with Custom C++ Operators
-<https://pytorch.org/tutorials/advanced/torch_script_custom_ops.html>`_
-tutorial.
-
-Macros
-------
-
-.. doxygendefine:: TORCH_LIBRARY
-
-.. doxygendefine:: TORCH_LIBRARY_IMPL
-
-Classes
--------
-
-.. doxygenclass:: torch::Library
-  :members:
-
-.. doxygenclass:: torch::CppFunction
-  :members:
-
-Functions
----------
-
-.. doxygengroup:: torch-dispatch-overloads
-  :content-only:
-
-.. doxygengroup:: torch-schema-overloads
-  :content-only:

docs/cpp/source/notes/tensor_basics.rst

@@ -11,8 +11,7 @@ include templates. That is, there is one ``Tensor`` type. It can hold a CPU or
 CUDA Tensor, and the tensor may have Doubles, Float, Ints, etc. This design
 makes it easy to write generic code without templating everything.
 
-See https://pytorch.org/cppdocs/api/namespace_at.html#functions for the provided
-API. Excerpt:
+Example functions:
 
 .. code-block:: cpp
 

docs/cpp/source/notes/tensor_creation.rst

@@ -146,9 +146,7 @@ allowed values for these axes at the moment are:
 .. tip::
 
         There exist "Rust-style" shorthands for dtypes, like ``kF32`` instead of
-        ``kFloat32``. See `here
-        <https://github.com/pytorch/pytorch/blob/master/torch/csrc/api/include/torch/types.h>`_
-        for the full list.
+        ``kFloat32``.
 
 
 An instance of ``TensorOptions`` stores a concrete value for each of these

docs/cpp/source/notes/tensor_cuda_stream.rst

@@ -3,11 +3,9 @@ Tensor CUDA Stream API
 
 A `CUDA Stream`_ is a linear sequence of execution that belongs to a specific CUDA device.
 The PyTorch C++ API supports CUDA streams with the CUDAStream class and useful helper functions to make streaming operations easy.
-You can find them in `CUDAStream.h`_. This note provides more details on how to use Pytorch C++ CUDA Stream APIs.
+This note provides details on how to use Pytorch C++ CUDA Stream APIs.
 
 .. _CUDA Stream: https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#streams
-.. _CUDAStream.h: https://pytorch.org/cppdocs/api/file_c10_cuda_CUDAStream.h.html#file-c10-cuda-cudastream-h
-.. _CUDAStreamGuard.h: https://pytorch.org/cppdocs/api/structc10_1_1cuda_1_1_c_u_d_a_stream_guard.html
 
 Acquiring CUDA stream
 *********************
@@ -65,7 +63,7 @@ Pytorch's C++ API provides the following ways to set CUDA stream:
   We recommend using ``CUDAStreamGuard``, instead, since it switches to the stream's device and makes it the current stream on that device.
   ``CUDAStreamGuard`` will also restore the current device and stream when it's destroyed
 
-2. Use ``CUDAStreamGuard`` to switch to a CUDA stream within a scope, it is defined in `CUDAStreamGuard.h`_
+2. Use ``CUDAStreamGuard`` to switch to a CUDA stream within a scope.
 
 .. tip::
 

docs/cpp/source/notes/tensor_indexing.rst

@@ -5,10 +5,8 @@ Indexing a tensor in the PyTorch C++ API works very similar to the Python API.
 All index types such as ``None`` / ``...`` / integer / boolean / slice / tensor
 are available in the C++ API, making translation from Python indexing code to C++
 very simple. The main difference is that, instead of using the ``[]``-operator
-similar to the Python API syntax, in the C++ API the indexing methods are:
-
-- ``torch::Tensor::index`` (`link <https://pytorch.org/cppdocs/api/classat_1_1_tensor.html#_CPPv4NK2at6Tensor5indexE8ArrayRefIN2at8indexing11TensorIndexEE>`_)
-- ``torch::Tensor::index_put_`` (`link <https://pytorch.org/cppdocs/api/classat_1_1_tensor.html#_CPPv4N2at6Tensor10index_put_E8ArrayRefIN2at8indexing11TensorIndexEERK6Tensor>`_)
+similar to the Python API syntax, in the C++ API the indexing methods are
+``torch::Tensor::index`` and `torch::Tensor::index_put_`.
 
 It's also important to note that index types such as ``None`` / ``Ellipsis`` / ``Slice``
 live in the ``torch::indexing`` namespace, and it's recommended to put ``using namespace torch::indexing``