[FFI][DOCS] Initial bringup of cpp docs (apache#18279)

This PR brings up initial version of cpp api docs.

Author: tqchen

docs/.gitignore

@@ -1,2 +1,2 @@
 _build
-**/generated/*.rst
+**/generated/*

docs/Makefile

@@ -27,14 +27,15 @@ help:
 
 .PHONY: help Makefile livehtml clean
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
 livehtml:
-	@sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) --ignore reference/cpp/generated
 
 clean:
 	rm -rf $(BUILDDIR)
 	rm -rf reference/python/generated
+	rm -rf reference/cpp/generated
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -33,3 +33,14 @@ Then build the doc
 ```bash
 make livehtml
 ```
+
+## Build with C++ Docs
+
+To build with C++ docs, we need to first install Doxygen. Then
+set the environment variable `BUILD_CPP_DOCS=1`, to turn on c++ docs.
+
+```bash
+BUILD_CPP_DOCS=1 make livehtml
+```
+
+Building c++ docs can take longer, so it is not on by default.

docs/conf.py

@@ -23,6 +23,9 @@
 
 os.environ["TVM_FFI_BUILD_DOCS"] = "1"
 
+build_exhale = os.environ.get("BUILD_CPP_DOCS", "0") == "1"
+
+
 # -- General configuration ------------------------------------------------
 
 # Load version from pyproject.toml
@@ -38,6 +41,7 @@
 # -- Extensions and extension configurations --------------------------------
 
 extensions = [
+    "breathe",
     "myst_parser",
     "nbsphinx",
     "autodocsumm",
@@ -48,6 +52,7 @@
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
+    "sphinx.ext.ifconfig",
     "sphinx_copybutton",
     "sphinx_reredirects",
     "sphinx_tabs.tabs",
@@ -56,6 +61,40 @@
     "sphinxcontrib.mermaid",
 ]
 
+if build_exhale:
+    extensions.append("exhale")
+
+breathe_default_project = "tvm-ffi"
+
+breathe_projects = {"tvm-ffi": "./_build/doxygen/xml"}
+
+exhaleDoxygenStdin = """
+INPUT = ../include
+PREDEFINED  += TVM_FFI_DLL= TVM_FFI_INLINE= TVM_FFI_EXTRA_CXX_API= __cplusplus=201703
+
+EXCLUDE_SYMBOLS   += *details*  *TypeTraits* std \
+                         *use_default_type_traits_v* *is_optional_type_v* *operator* \
+
+EXCLUDE_PATTERNS   += *details.h
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+"""
+
+exhaleAfterTitleDescription = """
+This page contains the full API index for the C++ API.
+"""
+
+# Setup the exhale extension
+exhale_args = {
+    "containmentFolder": "reference/cpp/generated",
+    "rootFileName": "index.rst",
+    "doxygenStripFromPath": "../include",
+    "rootFileTitle": "Full API Index",
+    "createTreeView": True,
+    "exhaleExecutesDoxygen": True,
+    "exhaleDoxygenStdin": exhaleDoxygenStdin,
+    "afterTitleDescription": exhaleAfterTitleDescription,
+}
 nbsphinx_allow_errors = True
 nbsphinx_execute = "never"
 
@@ -69,6 +108,7 @@
     "colon_fence",
     "html_image",
     "linkify",
+    "attrs_block",
     "substitution",
 ]
 

docs/guides/cpp_guide.md

@@ -14,6 +14,8 @@
 <!--- KIND, either express or implied.  See the License for the -->
 <!--- specific language governing permissions and limitations -->
 <!--- under the License. -->
+{#cpp-guide}
+
 # C++ Guide
 
 This guide introduces the tvm-ffi C++ API.

docs/index.rst

@@ -18,6 +18,10 @@
 Apache TVM FFI Documentation
 ============================
 
+Welcome to the documentation for TVM FFI. You can get started by reading the get started section,
+or reading through the guides and concepts sections.
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Get Started
@@ -40,8 +44,10 @@ Apache TVM FFI Documentation
 
    concepts/abi_overview.md
 
+
 .. toctree::
    :maxdepth: 1
    :caption: Reference
 
    reference/python/index.rst
+   reference/cpp/index.rst

docs/reference/cpp/index.rst

@@ -0,0 +1,107 @@
+..  Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+..    http://www.apache.org/licenses/LICENSE-2.0
+
+..  Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+C++ API
+=======
+
+This page contains the API reference for the C++ API. The full API index below
+can be a bit dense, so we recommend the following tips first:
+
+- Please read the :ref:`C++ Guide<cpp-guide>` for a high-level overview of the C++ API.
+
+  - The C++ Guide and examples will likely be sufficient to get started with most use cases.
+
+- The :ref:`cpp-key-classes` lists the key classes that are most commonly used.
+- You can go to the Full API Index at the bottom of this page to access the full list of APIs.
+
+  - We usually group the APIs by files. You can look at the file hierarchy in the
+    full API index and navigate to the specific file to find the APIs in that file.
+
+Header Organization
+-------------------
+
+The C++ APIs are organized into the following folders:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Folder
+     - Description
+   * - ``tvm/ffi/``
+     - Core functionalities that support Function, Any, Object, etc.
+   * - ``tvm/ffi/container/``
+     - Additional container types such as Array, Map, Shape, Tensor, Variant ...
+   * - ``tvm/ffi/reflection/``
+     - Reflection support for function and type information registration.
+   * - ``tvm/ffi/extra/``
+     - Extra APIs that are built on top.
+
+
+.. _cpp-key-classes:
+
+Key Classes
+-----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Class
+     - Description
+   * - :cpp:class:`tvm::ffi::Function`
+     - Type-erased function that implements the ABI.
+   * - :cpp:class:`tvm::ffi::Any`
+     - Type-erased container for any supported value.
+   * - :cpp:class:`tvm::ffi::AnyView`
+     - Lightweight view of Any without ownership.
+   * - :cpp:class:`tvm::ffi::Object`
+     - Base class for all heap-allocated FFI objects.
+   * - :cpp:class:`tvm::ffi::ObjectRef`
+     - Reference class for objects.
+   * - :cpp:class:`tvm::ffi::Tensor`
+     - Multi-dimensional tensor with DLPack support.
+   * - :cpp:class:`tvm::ffi::Shape`
+     - Tensor shape container.
+   * - :cpp:class:`tvm::ffi::Module`
+     - Dynamic library module that can load exported functions.
+   * - :cpp:class:`tvm::ffi::String`
+     - String type for FFI.
+   * - :cpp:class:`tvm::ffi::Bytes`
+     - Byte array type.
+   * - :cpp:class:`tvm::ffi::Array`
+     - Dynamic array container.
+   * - :cpp:class:`tvm::ffi::Tuple`
+     - Heterogeneous tuple container.
+   * - :cpp:class:`tvm::ffi::Map`
+     - Key-value map container.
+   * - :cpp:class:`tvm::ffi::Optional`
+     - Optional value wrapper.
+   * - :cpp:class:`tvm::ffi::Variant`
+     - Type-safe union container.
+
+
+
+.. _cpp-full-api-index:
+
+Full API Index
+--------------
+
+.. toctree::
+   :maxdepth: 2
+
+   generated/index.rst

docs/requirements.txt

@@ -1,4 +1,6 @@
 autodocsumm
+exhale
+breathe
 linkify-it-py
 matplotlib
 myst-parser