docs: Generate and host R documentation (#977)

This PR adds the standard-issue pkgdown site build to the documentation
(and fixes a few build errors that were identified as a result of
building in that environment). The Packaging / Documentation job
contains an artifact with the generated documentation and I've included
a few images below.

<img width="270" alt="Screenshot 2023-08-15 at 4 55 35 PM"
src="https://github.com/apache/arrow-adbc/assets/10995762/3841ee1b-e344-4683-ab9a-02c60be0f4ca">

<img width="604" alt="Screen Shot 2023-06-28 at 3 14 32 PM"
src="https://github.com/apache/arrow-adbc/assets/10995762/f6e27b08-f52c-4ece-aab8-b6afde1623df">

<img width="1110" alt="Screenshot 2023-08-15 at 4 56 06 PM"
src="https://github.com/apache/arrow-adbc/assets/10995762/8824e453-8c24-4867-91e8-5148ed3c7e50">

Closes #875.

ci/conda_env_docs.txt

@@ -26,3 +26,4 @@ sphinx-autobuild
 sphinx-copybutton
 sphinx-design
 sphinxcontrib-mermaid
+r-pkgdown

ci/scripts/docs_build.sh

@@ -28,6 +28,19 @@ main() {
     pushd "$source_dir/docs"
     make html
     make doctest
+    popd
+
+    for desc_file in $(find "${source_dir}/r" -name DESCRIPTION); do
+      local pkg=$(dirname "$desc_file")
+      local pkg_name=$(basename $pkg)
+      # Only build R documentation for installed packages (e.g., so that
+      # Python's documentation build can run without installing the R
+      # packages). Packages are installed in ci/scripts/r_build.sh
+      if Rscript -e "loadNamespace('$pkg_name')" ; then
+        R -e "pkgdown::build_site_github_pages(pkg = '$pkg', dest_dir = '$source_dir/docs/build/html/r/$pkg_name')"
+      fi
+    done
+
 }
 
 main "$@"

ci/scripts/r_build.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# 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.
+
+set -e
+
+: ${BUILD_ALL:=1}
+: ${BUILD_DRIVER_FLIGHTSQL:=${BUILD_ALL}}
+: ${BUILD_DRIVER_MANAGER:=${BUILD_ALL}}
+: ${BUILD_DRIVER_POSTGRESQL:=${BUILD_ALL}}
+: ${BUILD_DRIVER_SQLITE:=${BUILD_ALL}}
+: ${BUILD_DRIVER_SNOWFLAKE:=${BUILD_ALL}}
+
+if [[ $(uname) = "Darwin" ]]; then
+    ADBC_LIBRARY_SUFFIX="dylib"
+else
+    ADBC_LIBRARY_SUFFIX="so"
+fi
+
+install_pkg() {
+    local -r source_dir="${1}"
+    local -r install_dir="${2}"
+    local -r pkg="${3}"
+    R CMD INSTALL "${source_dir}/r/${pkg}" --preclean --library="${install_dir}"
+}
+
+main() {
+    local -r source_dir="${1}"
+    local -r install_dir="${2}"
+
+    R_LIBS_USER="${install_dir}" R -e 'install.packages("nanoarrow", repos = "https://cloud.r-project.org/")' --vanilla
+
+    if [[ "${BUILD_DRIVER_MANAGER}" -gt 0 ]]; then
+        install_pkg "${source_dir}" "${install_dir}" adbcdrivermanager
+    fi
+
+    if [[ "${BUILD_DRIVER_FLIGHTSQL}" -gt 0 ]]; then
+        install_pkg "${source_dir}" "${install_dir}" adbcflightsql
+    fi
+
+    if [[ "${BUILD_DRIVER_POSTGRESQL}" -gt 0 ]]; then
+        install_pkg "${source_dir}" "${install_dir}" adbcpostgresql
+    fi
+
+    if [[ "${BUILD_DRIVER_SQLITE}" -gt 0 ]]; then
+        install_pkg "${source_dir}" "${install_dir}" adbcsqlite
+    fi
+
+    if [[ "${BUILD_DRIVER_SNOWFLAKE}" -gt 0 ]]; then
+        install_pkg "${source_dir}" "${install_dir}" adbcsnowflake
+    fi
+}
+
+main "$@"

docker-compose.yml

@@ -28,7 +28,7 @@ services:
     volumes:
       - .:/adbc:delegated
     command: |
-      /bin/bash -c 'git config --global --add safe.directory /adbc && source /opt/conda/etc/profile.d/conda.sh && mamba create -y -n adbc -c conda-forge go --file /adbc/ci/conda_env_cpp.txt --file /adbc/ci/conda_env_docs.txt --file /adbc/ci/conda_env_python.txt && conda activate adbc && env ADBC_USE_ASAN=0 ADBC_USE_UBSAN=0 /adbc/ci/scripts/cpp_build.sh /adbc /adbc/build && env CGO_ENABLED=1 /adbc/ci/scripts/go_build.sh /adbc /adbc/build && /adbc/ci/scripts/python_build.sh /adbc /adbc/build && /adbc/ci/scripts/docs_build.sh /adbc'
+      /bin/bash -c 'git config --global --add safe.directory /adbc && source /opt/conda/etc/profile.d/conda.sh && mamba create -y -n adbc -c conda-forge go --file /adbc/ci/conda_env_cpp.txt --file /adbc/ci/conda_env_docs.txt --file /adbc/ci/conda_env_python.txt && conda activate adbc && env ADBC_USE_ASAN=0 ADBC_USE_UBSAN=0 /adbc/ci/scripts/cpp_build.sh /adbc /adbc/build && env CGO_ENABLED=1 /adbc/ci/scripts/go_build.sh /adbc /adbc/build && /adbc/ci/scripts/python_build.sh /adbc /adbc/build && /adbc/ci/scripts/r_build.sh /adbc && /adbc/ci/scripts/docs_build.sh /adbc'
 
   golang-sqlite-flightsql:
     image: ${REPO}:golang-${GO}-sqlite-flightsql

docs/source/index.rst

@@ -37,6 +37,7 @@ To learn more about ADBC, see the `introductory blog post
    Go <https://pkg.go.dev/github.com/apache/arrow-adbc/go/adbc>
    Java <java/index>
    Python <python/index>
+   R <r/index>
 
 .. toctree::
    :maxdepth: 1

docs/source/r/index.rst

@@ -0,0 +1,63 @@
+.. 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.
+
+===
+R
+===
+
+ADBC in R is implemented as a suite of R packages. Most users will
+interact with ADBC via the `adbcdrivermanager <adbcdrivermanager/index.html>`_
+package and use drivers that are also distributed as R packages. In
+addition to the low-level interface provided by adbcdrivermanager,
+you can use ``read_adbc()``, ``write_adbc()`` and ``execute_adbc()``
+to quickly interact with an ADBC connection or database.
+
+.. code-block:: r
+
+   library(adbcdrivermanager)
+
+   # Use the driver manager to connect to a database
+   db <- adbc_database_init(adbcsqlite::adbcsqlite(), uri = ":memory:")
+   con <- adbc_connection_init(db)
+
+   # Write a table
+   mtcars |>
+     write_adbc(con, "mtcars")
+
+   # Query it
+   con |>
+     read_adbc("SELECT * from mtcars") |>
+     tibble::as_tibble()
+
+   # Clean up
+   con |>
+     execute_adbc("DROP TABLE mtcars")
+   adbc_connection_release(con)
+   adbc_database_release(db)
+
+See individual package documentation for installation and usage
+details specific to each driver.
+
+---------------------
+Package documentation
+---------------------
+
+- `adbcdrivermanager <adbcdrivermanager/index.html>`_
+- `adbcflightsql <adbcflightsql/index.html>`_
+- `adbcpostgresql <adbcpostgresql/index.html>`_
+- `adbcsnowflake <adbcsnowflake/index.html>`_
+- `adbcsqlite <adbcsqlite/index.html>`_

r/adbcdrivermanager/.Rbuildignore

@@ -9,3 +9,6 @@
 ^\.covrignore$
 ^bootstrap\.R$
 ^cran-comments\.md$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

r/adbcdrivermanager/.gitignore

@@ -21,3 +21,4 @@
 .httr-oauth
 .DS_Store
 .vscode/
+docs

r/adbcdrivermanager/_pkgdown.yml

@@ -0,0 +1,30 @@
+# 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.
+
+url: ~
+template:
+  bootstrap: 5
+  # Link back to ADBC R documentation
+  includes:
+    before_title: |
+      <ul class="navbar-nav me-auto">
+        <li class="nav-item">
+          <a class="nav-link" href="../index.html">
+            <span class="fa fa-arrow-left"></span>
+          </a>
+        </li>
+      </ul>

r/adbcflightsql/.Rbuildignore

@@ -7,3 +7,6 @@
 ^configure\.win$
 ^\.vscode$
 ^src/go/tmp$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

r/adbcflightsql/.gitignore

@@ -17,3 +17,4 @@
 
 .Rproj.user
 windows/
+docs

r/adbcflightsql/_pkgdown.yml

@@ -0,0 +1,30 @@
+# 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.
+
+url: ~
+template:
+  bootstrap: 5
+  # Link back to ADBC R documentation
+  includes:
+    before_title: |
+      <ul class="navbar-nav me-auto">
+        <li class="nav-item">
+          <a class="nav-link" href="../index.html">
+            <span class="fa fa-arrow-left"></span>
+          </a>
+        </li>
+      </ul>

r/adbcflightsql/configure

@@ -33,7 +33,7 @@ if [ -z "$GO_BIN" ]; then
   GO_BIN=`which go`
 fi
 
-if [ -z "$GO_BIN"]; then
+if [ -z "$GO_BIN" ]; then
   if [ ! -f src/go/tmp/go/bin/go ]; then
     echo ""
     echo "Downloading and extracting Go into the package source directory:"
@@ -73,7 +73,7 @@ fi
 
 # On OSX we need -framework Security because of some dependency somewhere
 if [ `uname` = "Darwin" ]; then
-  PKG_LIBS="-framework Security -lresolv $PKG_LIBS"
+  PKG_LIBS="-framework Security $PKG_LIBS"
 fi
 
 PKG_LIBS="$PKG_LIBS $SYMBOL_ARGS"

r/adbcflightsql/src/Makevars.in

@@ -16,7 +16,7 @@
 # under the License.
 
 PKG_CPPFLAGS=-I$(CURDIR)/src -DADBC_EXPORT=""
-PKG_LIBS=-L$(CURDIR)/go -ladbc_driver_flightsql @libs@
+PKG_LIBS=-L$(CURDIR)/go -ladbc_driver_flightsql -lresolv @libs@
 
 CGO_CC = @cc@
 CGO_CXX = @cxx@

r/adbcpostgresql/.Rbuildignore

@@ -10,3 +10,6 @@
 ^configure\.win$
 ^windows$
 ^\.vscode$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

r/adbcpostgresql/.gitignore

@@ -17,3 +17,4 @@
 
 .Rproj.user
 windows/
+docs

r/adbcpostgresql/_pkgdown.yml

@@ -0,0 +1,30 @@
+# 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.
+
+url: ~
+template:
+  bootstrap: 5
+  # Link back to ADBC R documentation
+  includes:
+    before_title: |
+      <ul class="navbar-nav me-auto">
+        <li class="nav-item">
+          <a class="nav-link" href="../index.html">
+            <span class="fa fa-arrow-left"></span>
+          </a>
+        </li>
+      </ul>

r/adbcsnowflake/.Rbuildignore

@@ -7,3 +7,6 @@
 ^configure\.win$
 ^\.vscode$
 ^src/go/tmp$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

r/adbcsnowflake/.gitignore

@@ -17,3 +17,4 @@
 
 .Rproj.user
 windows/
+docs

r/adbcsnowflake/_pkgdown.yml

@@ -0,0 +1,30 @@
+# 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.
+
+url: ~
+template:
+  bootstrap: 5
+  # Link back to ADBC R documentation
+  includes:
+    before_title: |
+      <ul class="navbar-nav me-auto">
+        <li class="nav-item">
+          <a class="nav-link" href="../index.html">
+            <span class="fa fa-arrow-left"></span>
+          </a>
+        </li>
+      </ul>

r/adbcsnowflake/configure

@@ -33,7 +33,7 @@ if [ -z "$GO_BIN" ]; then
   GO_BIN=`which go`
 fi
 
-if [ -z "$GO_BIN"]; then
+if [ -z "$GO_BIN" ]; then
   if [ ! -f src/go/tmp/go/bin/go ]; then
     echo ""
     echo "Downloading and extracting Go into the package source directory:"

r/adbcsqlite/.Rbuildignore

@@ -7,3 +7,6 @@
 ^src/sqlite3\.c$
 ^src/sqlite3\.h$
 ^\.vscode$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$

r/adbcsqlite/.gitignore

@@ -16,3 +16,4 @@
 # under the License.
 
 .Rproj.user
+docs