docs(c/driver/framework): Add documentation for building a driver using the driver framework

[paleolimbot]

This PR adds a tutorial with how to build a basic driver using the C++ framework. You can read the recipe by downloading the docs.tgz asset from the CI job:

https://github.com/apache/arrow-adbc/actions/runs/11431710883/artifacts/2080179525

Example driver in action:

import os
import pyarrow
from pathlib import Path
from adbc_driver_manager import dbapi


def connect(uri: str):
    build_dir = Path(__file__).parent / "build"
    for lib in [
        "libdriver_example.dylib",
        "libdriver_example.so",
        "driver_example.dll",
    ]:
        driver_lib = build_dir / lib
        if driver_lib.exists():
            return dbapi.connect(
                driver=str(driver_lib.resolve()), db_kwargs={"uri": uri}
            )

    raise RuntimeError("Can't find driver shared object")


with connect(uri=Path(__file__).parent.as_uri()) as con:
    data = pyarrow.table({"col": [1, 2, 3]})
    with con.cursor() as cur:
        cur.adbc_ingest("example.arrows", data, mode="create")

    with con.cursor() as cur:
        cur.execute("SELECT * FROM example.arrows")
        print(cur.fetchall())

    os.unlink(Path(__file__).parent / "example.arrows")
#> [(1,), (2,), (3,)]

[lidavidm]

If I'm not mistaken we already have cpp_recipe.sh for testing? Can we just fold all the test scripts into one?

(We could even have a single parent CMake that adds the quickstart/driver example as child CMakes, though I can understand if you want the driver example to be fully self-contained there)

[paleolimbot]

I think a self-contained CMakeLists.txt is more realistic although I'm open to any suggestions here! I mostly just tried to emulate the existing art here which is great!

[lidavidm]

Ah I'm mostly just saying, we can just have a single shell script to invoke all the CMake builds for recipes. Not too big deal to me though

[paleolimbot]

I think I did this (but happy to restructure as required!)

[WillAyd]

This would be nice but we don't have this worked out in the main project yet either do we? Maybe worth punting until then

[paleolimbot]

Removed!

[WillAyd]

I am +1 to including this in the example - I think the test is helpful to read

[paleolimbot]

Ok! I leaned into this comment and made it a part of the recipe!

[lidavidm]

Can we update this now?

[lidavidm]

I think something like

:cpp:class:`adbc::driver::Option`

should work now (and eventually result in a proper link to the API docs from the prose docs), though no big deal either way (it can be finicky to set up and test locally)

[paleolimbot]

I'll give it a try!

[lidavidm]

Hmm, there's something not right with the scrape...I'll see if I can take a look too

  File "/adbc/docs/source/ext/doxygen_inventory.py", line 209, in <module>
    main()
  File "/adbc/docs/source/ext/doxygen_inventory.py", line 193, in main
    domains = make_fake_domains(args.html_path, args.xml_path, args.url)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/adbc/docs/source/ext/doxygen_inventory.py", line 145, in make_fake_domains
    for domain, name, typ, anchor, url in scrape_links(item_id_to_url, root):
                                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/adbc/docs/source/ext/doxygen_inventory.py", line 66, in scrape_links
    url = item_id_to_url[anchor]
          ~~~~~~~~~~~~~~^^^^^^^^
KeyError: 'structadbc_1_1driver_1_1Status_1_1Impl'

[paleolimbot]

I ran out of time today to debug but I can take a look tomorrow too!

[lidavidm]

I took a look and interestingly, Status::Impl is documented in the XML, but not in the HTML.

[lidavidm]

Ok I think the main issue is that I just haven't implemented enough to also scrape C++ headers well...

[lidavidm]

Ok, I think that should fix the main things...

[lidavidm]

Sorry, I pushed a bunch of crap here...let's hope the docs work now 😅

[paleolimbot]

No problem! Thank you! They look great!