docs: link to Doxygen output instead of using breathe

Fixes apache#1935.

.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

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

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.
 ///

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>

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

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

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

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()

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.

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

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`.

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

docs/source/driver/flight_sql.rst

@@ -82,7 +82,7 @@ Usage
 =====
 
 To connect to a database, supply the "uri" parameter when constructing
-the :cpp:class:`AdbcDatabase`.
+the :c:struct:`AdbcDatabase`.
 
 .. tab-set::
 
@@ -183,7 +183,7 @@ few optional authentication schemes:
 - An HTTP-style scheme mimicking the Arrow Flight SQL JDBC driver.
 
   Set the options ``username`` and ``password`` on the
-  :cpp:class:`AdbcDatabase`.  Alternatively, set the option
+  :c:struct:`AdbcDatabase`.  Alternatively, set the option
   ``adbc.flight.sql.authorization_header`` for full control.
 
   The client provides credentials sending an ``authorization`` from
@@ -272,8 +272,8 @@ Custom Call Headers
 -------------------
 
 Custom HTTP headers can be attached to requests via options that apply
-to :cpp:class:`AdbcDatabase`, :cpp:class:`AdbcConnection`, and
-:cpp:class:`AdbcStatement`.
+to :c:struct:`AdbcDatabase`, :c:struct:`AdbcConnection`, and
+:c:struct:`AdbcStatement`.
 
 ``adbc.flight.sql.rpc.call_header.<HEADER NAME>``
   Add the header ``<HEADER NAME>`` to outgoing requests with the given
@@ -301,7 +301,7 @@ All partitions are fetched in parallel.  A limited number of batches
 are queued per partition.  Data is returned to the client in the order
 of the partitions.
 
-Some behavior can be configured on the :cpp:class:`AdbcStatement`:
+Some behavior can be configured on the :c:struct:`AdbcStatement`:
 
 ``adbc.rpc.result_queue_size``
     The number of batches to queue per partition.  Defaults to 5.
@@ -313,27 +313,27 @@ Incremental Execution
 
 By setting :c:macro:`ADBC_STATEMENT_OPTION_INCREMENTAL`, you can use
 nonblocking execution with this driver.  This changes the behavior of
-:func:`AdbcStatementExecutePartitions` only.  When enabled, ExecutePartitions
-will return every time there are new partitions (in Flight SQL terms, when
-there are new FlightEndpoints) from the server, instead of blocking until the
-query is complete.
+:c:func:`AdbcStatementExecutePartitions` only.  When enabled,
+ExecutePartitions will return every time there are new partitions (in Flight
+SQL terms, when there are new FlightEndpoints) from the server, instead of
+blocking until the query is complete.
 
-Some behavior can be configured on the :cpp:class:`AdbcStatement`:
+Some behavior can be configured on the :c:struct:`AdbcStatement`:
 
 ``adbc.flight.sql.statement.exec.last_flight_info``
     Get the serialized bytes for the most recent ``FlightInfo`` returned by
     the service.  This is a low-level option intended for advanced usage.  It
     is most useful when incremental execution is enabled, for inspecting the
     latest server response without waiting for
-    :func:`AdbcStatementExecutePartitions` to return.
+    :c:func:`AdbcStatementExecutePartitions` to return.
 
     Python: :attr:`adbc_driver_flightsql.StatementOptions.LAST_FLIGHT_INFO`
 
 Metadata
 --------
 
 The driver currently will not populate column constraint info (foreign
-keys, primary keys, etc.) in :cpp:func:`AdbcConnectionGetObjects`.
+keys, primary keys, etc.) in :c:func:`AdbcConnectionGetObjects`.
 Also, catalog filters are evaluated as simple string matches, not
 ``LIKE``-style patterns.
 
@@ -390,7 +390,7 @@ Timeouts
 --------
 
 By default, timeouts are not used for RPC calls.  They can be set via
-special options on :cpp:class:`AdbcConnection`.  In general, it is
+special options on :c:struct:`AdbcConnection`.  In general, it is
 best practice to set timeouts to avoid unexpectedly getting stuck.
 The options are as follows:
 
@@ -409,7 +409,7 @@ The options are as follows:
     calls.
 
     For example, this controls the timeout of the underlying Flight
-    calls that implement :func:`AdbcStatementExecuteQuery`.
+    calls that implement :c:func:`AdbcStatementExecuteQuery`.
 
     Python: :attr:`adbc_driver_flightsql.ConnectionOptions.TIMEOUT_QUERY`
 
@@ -422,7 +422,7 @@ The options are as follows:
 
     Python: :attr:`adbc_driver_flightsql.ConnectionOptions.TIMEOUT_UPDATE`
 
-There is also a timeout that is set on the :cpp:class:`AdbcDatabase`:
+There is also a timeout that is set on the :c:struct:`AdbcDatabase`:
 
 ``adbc.flight.sql.rpc.timeout_seconds.connect``
     A timeout (in floating-point seconds) for establishing a connection.  The
@@ -434,6 +434,6 @@ Transactions
 The driver supports transactions.  It will first check the server's
 SqlInfo to determine whether this is supported.  Otherwise,
 transaction-related ADBC APIs will return
-:c:type:`ADBC_STATUS_NOT_IMPLEMENTED`.
+:c:macro:`ADBC_STATUS_NOT_IMPLEMENTED`.
 
 .. _DBAPI 2.0: https://peps.python.org/pep-0249/

docs/source/driver/postgresql.rst

@@ -81,7 +81,7 @@ Usage
 =====
 
 To connect to a database, supply the "uri" parameter when constructing
-the :cpp:class:`AdbcDatabase`.  This should be a `connection URI
+the :c:struct:`AdbcDatabase`.  This should be a `connection URI
 <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING>`_.
 
 .. tab-set::