docs: link to Doxygen output instead of using breathe

Fixes apache#1935.
lidavidm · Oct 7, 2024 · 8df85d2 · 8df85d2
1 parent e10da21
commit 8df85d2
Show file tree

Hide file tree

Showing 33 changed files with 486 additions and 180 deletions.
diff --git a/.github/workflows/native-unix.yml b/.github/workflows/native-unix.yml
@@ -677,7 +677,7 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest"]
-        python: ["3.11"]
+        python: ["3.12"]
     steps:
       - uses: actions/checkout@v4
         with:

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -105,7 +105,7 @@ repos:
       name: Ensure CGO adbc.h is syncd
       language: script
       pass_filenames: true
-      files: '(c/driver_manager/adbc_driver_manager\.)|(^adbc\.h)'
+      files: '^c/include/arrow-adbc/.*\.h$'
       entry: "./ci/scripts/run_cgo_drivermgr_check.sh"
   - repo: https://github.com/doublify/pre-commit-rust
     rev: v1.0

diff --git a/c/apidoc/Doxyfile b/c/apidoc/Doxyfile
@@ -1007,7 +1007,7 @@ EXCLUDE_PATTERNS       =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        =
+EXCLUDE_SYMBOLS        = ADBC ADBC_DRIVER_MANAGER_H
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include

diff --git a/c/include/arrow-adbc/adbc.h b/c/include/arrow-adbc/adbc.h
@@ -1972,7 +1972,7 @@ AdbcStatusCode AdbcStatementExecuteQuery(struct AdbcStatement* statement,
 /// \since ADBC API revision 1.1.0
 ///
 /// \param[in] statement The statement to execute.
-/// \param[out] out The result schema.
+/// \param[out] schema The result schema.
 /// \param[out] error An optional location to return an error
 ///   message if necessary.
 ///

diff --git a/c/include/arrow-adbc/adbc_driver_manager.h b/c/include/arrow-adbc/adbc_driver_manager.h
@@ -15,6 +15,11 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/// \file arrow-adbc/adbc_driver_manager.h ADBC Driver Manager
+///
+/// A helper library to dynamically load and use multiple ADBC drivers in the
+/// same process.
+
 #pragma once
 
 #include <arrow-adbc/adbc.h>

diff --git a/ci/conda_env_docs.txt b/ci/conda_env_docs.txt
@@ -15,17 +15,17 @@
 # specific language governing permissions and limitations
 # under the License.
 
-breathe
 doxygen
-# XXX(https://github.com/apache/arrow-adbc/issues/987)
-furo>=2023.09.10
+furo
 make
 # Needed to install mermaid
 nodejs
 numpydoc
 pytest
-# XXX: we're stuck until we can get rid of Breathe
-sphinx=6.*
+# XXX: furo on conda-forge says it isn't compatible with sphinx 8, but in
+# reality it is (the conda metadata for one of its dependencies is wrong)
+# https://github.com/conda-forge/sphinx-basic-ng-feedstock/pull/11
+sphinx >=7
 sphinx-autobuild
 sphinx-copybutton
 sphinx-design

diff --git a/ci/scripts/docs_build.sh b/ci/scripts/docs_build.sh
@@ -31,17 +31,27 @@ main() {
 
     pushd "$source_dir/docs"
     # The project name/version don't really matter here.
+    python "$source_dir/docs/source/ext/doxygen_inventory.py" \
+           "ADBC C" \
+           "version" \
+           --html-path "$source_dir/c/apidoc/html" \
+           --xml-path "$source_dir/c/apidoc/xml" \
+           "cpp/api" \
+           "$source_dir/c/apidoc"
     python "$source_dir/docs/source/ext/javadoc_inventory.py" \
-           "ADBC" \
+           "ADBC Java" \
            "version" \
            "$source_dir/java/target/site/apidocs" \
            "java/api"
 
     # We need to determine the base URL without knowing it...
     # Inject a dummy URL here, and fix it up in website_build.sh
     export ADBC_INTERSPHINX_MAPPING_java_adbc="http://javadocs.home.arpa/;$source_dir/java/target/site/apidocs/objects.inv"
+    export ADBC_INTERSPHINX_MAPPING_cpp_adbc="http://javadocs.home.arpa/;$source_dir/c/apidoc/objects.inv"
 
-    make html
+    sphinx-build --builder html --nitpicky --fail-on-warning --keep-going source build/html
+    rm -rf "$source_dir/docs/build/html/cpp/api"
+    cp -r "$source_dir/c/apidoc/html" "$source_dir/docs/build/html/cpp/api"
     rm -rf "$source_dir/docs/build/html/java/api"
     cp -r "$source_dir/java/target/site/apidocs" "$source_dir/docs/build/html/java/api"
     make doctest

diff --git a/ci/scripts/run_cgo_drivermgr_check.sh b/ci/scripts/run_cgo_drivermgr_check.sh
@@ -32,8 +32,8 @@ main() {
 
   for f in "$@"; do
     fn=$(basename $f)
-    if ! diff -q "$f" "go/adbc/drivermgr/$fn" &>/dev/null; then
-      >&2 echo "OUT OF SYNC: $f differs from go/adbc/drivermgr/$fn"
+    if ! diff -q "$f" "go/adbc/drivermgr/arrow-adbc/$fn" &>/dev/null; then
+      >&2 echo "OUT OF SYNC: $f differs from go/adbc/drivermgr/arrow-adbc/$fn"
       popd
       return 1
     fi

diff --git a/docs/source/AdbcQuadrants.mmd b/docs/source/AdbcQuadrants.mmd
@@ -0,0 +1,27 @@
+%% 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.
+
+quadrantChart
+    x-axis Database-specific --> Database-agnostic
+    y-axis Row-oriented --> Arrow-native
+
+    ADBC: [0.9, 0.9]
+    JDBC: [0.9, 0.1]
+    ODBC: [0.9, 0.2]
+    "Flight SQL": [0.6, 0.9]
+    "BigQuery API": [0.1, 0.8]
+    "PostgreSQL protocol": [0.4, 0.1]
diff --git a/docs/source/AdbcQuadrants.mmd.svg b/docs/source/AdbcQuadrants.mmd.svg
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -43,7 +43,6 @@
     "adbc_cookbook",
     # generic directives to enable intersphinx for java
     "adbc_java_domain",
-    "breathe",
     "numpydoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
@@ -78,13 +77,6 @@
     "show-inheritance": True,
 }
 
-# -- Options for Breathe -----------------------------------------------------
-
-breathe_default_project = "adbc"
-breathe_projects = {
-    "adbc": "../../c/apidoc/xml/",
-}
-
 # -- Options for doctest -----------------------------------------------------
 
 doctest_global_setup = """
@@ -132,10 +124,6 @@ def _find_intersphinx_mappings():
             url, _, path = val.partition(";")
             print("[ADBC] Found Intersphinx mapping", name)
             intersphinx_mapping[name] = (url, path)
-        #         "adbc_java": (
-        #     "http://localhost:8000/",
-        #     "/home/lidavidm/Code/arrow-adbc/java/target/site/apidocs/objects.inv",
-        # ),
 
 
 _find_intersphinx_mappings()

diff --git a/docs/source/cpp/api/adbc.rst b/docs/source/cpp/api/adbc.rst
diff --git a/docs/source/cpp/api/adbc_driver_manager.rst b/docs/source/cpp/api/adbc_driver_manager.rst
diff --git a/docs/source/cpp/api/index.rst b/docs/source/cpp/api/index.rst
@@ -19,8 +19,5 @@
 C/C++ API Reference
 ===================
 
-.. toctree::
-   :maxdepth: 2
-
-   adbc
-   adbc_driver_manager
+This is a stub page for the Doxygen documentation. If you're seeing this page,
+it means that the actual documentation was not generated.
diff --git a/docs/source/cpp/concurrency.rst b/docs/source/cpp/concurrency.rst
@@ -47,7 +47,7 @@ AdbcConnection:
    /* What happens to the result set of stmt1? */
 
 What happens if the client application calls
-:cpp:func:`AdbcStatementExecuteQuery` on ``stmt1``, then on ``stmt2``,
+:c:func:`AdbcStatementExecuteQuery` on ``stmt1``, then on ``stmt2``,
 without reading the result set of ``stmt1``?  Some existing client
 libraries/protocols, like libpq, don't support concurrent execution of
 queries from a single connection.  So the driver would have to

diff --git a/docs/source/cpp/driver_manager.rst b/docs/source/cpp/driver_manager.rst
@@ -94,13 +94,12 @@ Then they can be used via CMake, e.g.:
 Usage
 =====
 
-To create a database, use the :cpp:class:`AdbcDatabase` API as usual,
-but during initialization, provide two additional parameters in
-addition to the driver-specific connection parameters: ``driver`` and
-(optionally) ``entrypoint``.  ``driver`` must be the name of a library
-to load, or the path to a library to load. ``entrypoint``, if
-provided, should be the name of the symbol that serves as the ADBC
-entrypoint (see :cpp:type:`AdbcDriverInitFunc`).
+To create a database, use the :c:struct:`AdbcDatabase` API as usual, but
+during initialization, provide two additional parameters in addition to the
+driver-specific connection parameters: ``driver`` and (optionally)
+``entrypoint``.  ``driver`` must be the name of a library to load, or the path
+to a library to load. ``entrypoint``, if provided, should be the name of the
+symbol that serves as the ADBC entrypoint (see :c:type:`AdbcDriverInitFunc`).
 
 .. code-block:: c
 
@@ -120,5 +119,5 @@ entrypoint (see :cpp:type:`AdbcDriverInitFunc`).
 API Reference
 =============
 
-The driver manager includes a few additional functions beyond the ADBC
-API.  See the API reference: :doc:`./api/adbc_driver_manager`.
+The driver manager includes a few additional functions beyond the ADBC API.
+See the API reference: :external+cpp_adbc:doc:`adbc_driver_manager.h`.
diff --git a/docs/source/cpp/recipe/quickstart.cc b/docs/source/cpp/recipe/quickstart.cc
@@ -139,7 +139,7 @@ int main() {
   /// -----------------
   ///
   /// We execute a query by setting the query on the statement, then
-  /// calling :cpp:func:`AdbcStatementExecuteQuery`.  The results come
+  /// calling :c:func:`AdbcStatementExecuteQuery`.  The results come
   /// back through the `Arrow C Data Interface`_.
   ///
   /// .. _Arrow C Data Interface: https://arrow.apache.org/docs/format/CDataInterface.html