add cpp api reference (#618)

Summary:
Pull Request resolved: #618

Adding cpp docs and updating the build system for the docs to support doxygen and breath (connects sphinx and doxygen).

If anyone in the future wants to add similar cpp docs they can just reference their cpp classes and methods like we do in executorch-runtime-api-reference.rst, and then add the corresponding .h files to Doxyfile's INPUT arg.

Reviewed By: svekars, cccclai

Differential Revision: D49924199

fbshipit-source-id: 6abc26166158d5ab9ff70f6b9904269ec9d62489

Author: JacobSzwejbka

.ci/docker/build.sh

@@ -36,6 +36,8 @@ TORCH_VERSION=$(cat ci_commit_pins/pytorch.txt)
 TORCHAUDIO_VERSION=$(cat ci_commit_pins/audio.txt)
 TORCHVISION_VERSION=$(cat ci_commit_pins/vision.txt)
 
+BUILD_DOCS=1
+
 # Copy requirements-lintrunner.txt from root to here
 cp ../../requirements-lintrunner.txt ./
 
@@ -51,6 +53,7 @@ docker build \
   --build-arg "TORCHVISION_VERSION=${TORCHVISION_VERSION}.${NIGHTLY}" \
   --build-arg "BUCK2_VERSION=${BUCK2_VERSION}" \
   --build-arg "LINTRUNNER=${LINTRUNNER}" \
+  --build-arg "BUILD_DOCS=${BUILD_DOCS}" \
   -f "${OS}"/Dockerfile \
   "$@" \
   .

.ci/docker/common/install_docs_reqs.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Copyright (c) Meta Platforms, Inc. and affiliates.
+# All rights reserved.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+
+set -ex
+
+if [ -n "$BUILD_DOCS" ]; then
+  apt-get update
+  # Ignore error if gpg-agent doesn't exist (for Ubuntu 16.04)
+  apt-get install -y gpg-agent || :
+
+  curl --retry 3 -sL https://deb.nodesource.com/setup_16.x | sudo -E bash -
+  sudo apt-get install -y nodejs
+
+  curl --retry 3 -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
+  echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
+
+  apt-get update
+  apt-get install -y --no-install-recommends yarn
+  yarn global add katex --prefix /usr/local
+
+  sudo apt-get -y install doxygen
+
+  apt-get autoclean && apt-get clean
+  rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+fi

.ci/docker/requirements-ci.txt

@@ -15,8 +15,11 @@ hypothesis==6.84.2
 parameterized==0.9.0
 
 # Doc build requirements
-sphinx==5.0.0
+sphinx==4.5.0
 sphinx-gallery
+breathe==4.35.0
+exhale==0.3.6
+docutils==0.16
 matplotlib
 # PyTorch Theme
 -e git+https://github.com/pytorch/pytorch_sphinx_theme.git#egg=pytorch_sphinx_theme

.ci/docker/ubuntu/Dockerfile

@@ -24,6 +24,11 @@ RUN bash ./install_buck.sh && rm install_buck.sh
 COPY ./common/install_user.sh install_user.sh
 RUN bash ./install_user.sh && rm install_user.sh
 
+# Install docs
+ARG BUILD_DOCS
+COPY ./common/install_docs_reqs.sh install_docs_reqs.sh
+RUN bash ./install_docs_reqs.sh && rm install_docs_reqs.sh
+
 # Install conda and other dependencies
 ARG MINICONDA_VERSION
 ARG PYTHON_VERSION

.github/workflows/doc-build.yml

@@ -46,6 +46,7 @@ jobs:
 
         # Build docset:
         cd docs
+        doxygen source/Doxyfile
         make html
         cd ..
 

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -WT --keep-going
+# SPHINXOPTS    = -WT --keep-going TODO(T165752164) fix sphinx warnings around preprocess macros in cpp like __ET_DEPRECATED
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = ExecuTorch
 SOURCEDIR     = source