docs: describe how drivers/driver manager relate

Fixes #1651.

.github/workflows/dev_pr/title_check.py

@@ -63,25 +63,26 @@ def matches_commit_format(root: Path, title: str) -> typing.List[str]:
         reasons.append(f"Invalid commit type: {commit_type}")
 
     components = m.group(2)
-    if not components.strip():
-        reasons.append("Invalid components: must not be empty")
-
-    components = components.split(",")
-    for component in components:
-        if component != component.strip():
-            reasons.append(
-                f"Invalid component: must have no trailing space: {component}"
-            )
-        elif not valid_component.match(component):
-            reasons.append(
-                "Invalid component: must be alphanumeric with "
-                f"dashes, slashes, and underscores: {component}"
-            )
-        elif component != "format" and not Path(component).exists():
-            reasons.append(
-                "Invalid component: must reference a file "
-                f"or directory in the repo: {component}"
-            )
+    if components is not None:
+        if not components.strip():
+            reasons.append("Invalid components: must not be empty")
+
+        components = components.split(",")
+        for component in components:
+            if component != component.strip():
+                reasons.append(
+                    f"Invalid component: must have no trailing space: {component}"
+                )
+            elif not valid_component.match(component):
+                reasons.append(
+                    "Invalid component: must be alphanumeric with "
+                    f"dashes, slashes, and underscores: {component}"
+                )
+            elif component != "format" and not Path(component).exists():
+                reasons.append(
+                    "Invalid component: must reference a file "
+                    f"or directory in the repo: {component}"
+                )
 
     subject = m.group(3)
     if subject.strip() != subject:

docs/mermaid.makefile

@@ -18,6 +18,9 @@
 # Generate Mermaid diagrams statically.  Sphinx has a mermaid
 # extension, but this causes issues with the page shifting during
 # load.
+# First: npm install -g @mermaid-js/mermaid-cli
+# (if you are using Conda, this will not be "global" but rather install to
+# your Conda prefix)
 # Use as: make -f mermaid.makefile -j all
 
 MERMAID := $(shell find source/ -type f -name '*.mmd')
@@ -27,7 +30,10 @@ define LICENSE
 endef
 
 %.mmd.svg : %.mmd
-	mmdc --input $< --output $@
+# XXX: mermaid doesn't properly handle comments in all layouts (the parser is
+# written entirely from scratch each time, it looks like), so strip them
+# manually
+	grep -E -v "^%" $< | mmdc --input - --output $@
 # Prepend the license header
 	mv $@ [email protected]
 	echo "<!--" >> $@

docs/source/_static/css/custom.css

@@ -24,3 +24,14 @@ p.admonition-title {
     display: block;
     margin: 0 auto;
 }
+
+figcaption {
+    font-style: italic;
+    margin: 0 auto;
+    text-wrap: balance;
+    width: 90%;
+}
+
+h1, h2, h3, h4 {
+    text-wrap: balance;
+}

docs/source/faq.rst

@@ -146,6 +146,17 @@ JDBC driver in a bespoke Arrow-based API.
 .. _arrow-jdbc: https://central.sonatype.com/artifact/org.apache.arrow/arrow-jdbc/11.0.0
 .. _Turbodbc: https://turbodbc.readthedocs.io/en/latest/
 
+What is the ADBC driver manager?
+================================
+
+The driver manager (in C/C++) is a library that implements the driver API but
+dynamically loads and manages multiple drivers behind the scenes.  It allows
+applications to link to a single library but use more than one driver at a
+time.  This avoids symbol conflicts between multiple drivers that would
+otherwise all provide the same ADBC APIs under the same names.
+
+For an in-depth look, see :doc:`format/how_manager`.
+
 What is the ADBC SQL dialect?
 =============================
 

docs/source/format/DriverAlias.mmd

@@ -0,0 +1,32 @@
+%% 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.
+
+block-beta
+    columns 3
+    app["<b>Application</b>"]:3
+
+    space:3
+
+    driver["<b>Driver</b>"]:3
+    AdbcStatementExecuteQuery
+    AdbcStatementSetSqlQuery
+    ...
+    SqliteStatementExecuteQuery
+    SqliteStatementSetSqlQuery
+    ...
+
+    app --> SqliteStatementExecuteQuery

docs/source/format/DriverDirectLink.mmd

@@ -0,0 +1,29 @@
+%% 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.
+
+block-beta
+    columns 3
+    app["<b>Application</b>"]:3
+
+    space:3
+
+    driver["<b>Driver</b>"]:3
+    AdbcStatementExecuteQuery
+    AdbcStatementSetSqlQuery
+    ...
+
+    app --> AdbcStatementExecuteQuery