This is an automated email from the ASF dual-hosted git repository.
paleolimbot pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new 500cb6b3 docs: Generate and host R documentation (#977)
500cb6b3 is described below
commit 500cb6b3692a76abf325c8da1227e15a0c5c73fc
Author: Dewey Dunnington <[email protected]>
AuthorDate: Tue Aug 15 18:12:47 2023 -0300
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 | 1 +
ci/scripts/docs_build.sh | 13 +++++
ci/scripts/r_build.sh | 68 ++++++++++++++++++++++
docker-compose.yml | 2 +-
docs/source/index.rst | 1 +
docs/source/r/index.rst | 63 ++++++++++++++++++++
r/adbcdrivermanager/.Rbuildignore | 3 +
r/adbcdrivermanager/.gitignore | 1 +
.../adbcdrivermanager/_pkgdown.yml | 24 ++++----
r/adbcflightsql/.Rbuildignore | 3 +
r/adbcflightsql/.gitignore | 1 +
.../adbcflightsql/_pkgdown.yml | 24 ++++----
r/adbcflightsql/configure | 4 +-
r/adbcflightsql/src/Makevars.in | 2 +-
r/adbcpostgresql/.Rbuildignore | 3 +
r/adbcpostgresql/.gitignore | 1 +
.../adbcpostgresql/_pkgdown.yml | 24 ++++----
r/adbcsnowflake/.Rbuildignore | 3 +
r/adbcsnowflake/.gitignore | 1 +
.../adbcsnowflake/_pkgdown.yml | 24 ++++----
r/adbcsnowflake/configure | 2 +-
r/adbcsqlite/.Rbuildignore | 3 +
r/adbcsqlite/.gitignore | 1 +
ci/conda_env_docs.txt => r/adbcsqlite/_pkgdown.yml | 24 ++++----
24 files changed, 236 insertions(+), 60 deletions(-)
diff --git a/ci/conda_env_docs.txt b/ci/conda_env_docs.txt
index 105ea10a..008b61d1 100644
--- a/ci/conda_env_docs.txt
+++ b/ci/conda_env_docs.txt
@@ -26,3 +26,4 @@ sphinx-autobuild
sphinx-copybutton
sphinx-design
sphinxcontrib-mermaid
+r-pkgdown
diff --git a/ci/scripts/docs_build.sh b/ci/scripts/docs_build.sh
index 917d9823..261786b9 100755
--- a/ci/scripts/docs_build.sh
+++ b/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 "$@"
diff --git a/ci/scripts/r_build.sh b/ci/scripts/r_build.sh
new file mode 100755
index 00000000..79af0e89
--- /dev/null
+++ b/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 "$@"
diff --git a/docker-compose.yml b/docker-compose.yml
index e65d9359..eea987a1 100644
--- a/docker-compose.yml
+++ b/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/bui [...]
+ /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/bui [...]
golang-sqlite-flightsql:
image: ${REPO}:golang-${GO}-sqlite-flightsql
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 76c4ebf3..69551b0b 100644
--- a/docs/source/index.rst
+++ b/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
diff --git a/docs/source/r/index.rst b/docs/source/r/index.rst
new file mode 100644
index 00000000..52fa4f13
--- /dev/null
+++ b/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>`_
diff --git a/r/adbcdrivermanager/.Rbuildignore
b/r/adbcdrivermanager/.Rbuildignore
index 9049d730..c74a5d2e 100644
--- a/r/adbcdrivermanager/.Rbuildignore
+++ b/r/adbcdrivermanager/.Rbuildignore
@@ -9,3 +9,6 @@
^\.covrignore$
^bootstrap\.R$
^cran-comments\.md$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$
diff --git a/r/adbcdrivermanager/.gitignore b/r/adbcdrivermanager/.gitignore
index 2050b550..b58d5bd9 100644
--- a/r/adbcdrivermanager/.gitignore
+++ b/r/adbcdrivermanager/.gitignore
@@ -21,3 +21,4 @@
.httr-oauth
.DS_Store
.vscode/
+docs
diff --git a/ci/conda_env_docs.txt b/r/adbcdrivermanager/_pkgdown.yml
similarity index 71%
copy from ci/conda_env_docs.txt
copy to r/adbcdrivermanager/_pkgdown.yml
index 105ea10a..4df7b75e 100644
--- a/ci/conda_env_docs.txt
+++ b/r/adbcdrivermanager/_pkgdown.yml
@@ -15,14 +15,16 @@
# specific language governing permissions and limitations
# under the License.
-breathe
-doxygen
-furo
-make
-numpydoc
-pytest
-sphinx>=5.0
-sphinx-autobuild
-sphinx-copybutton
-sphinx-design
-sphinxcontrib-mermaid
+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>
diff --git a/r/adbcflightsql/.Rbuildignore b/r/adbcflightsql/.Rbuildignore
index 9f12a1fa..389c04f5 100644
--- a/r/adbcflightsql/.Rbuildignore
+++ b/r/adbcflightsql/.Rbuildignore
@@ -7,3 +7,6 @@
^configure\.win$
^\.vscode$
^src/go/tmp$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$
diff --git a/r/adbcflightsql/.gitignore b/r/adbcflightsql/.gitignore
index d025a1b1..11519d40 100644
--- a/r/adbcflightsql/.gitignore
+++ b/r/adbcflightsql/.gitignore
@@ -17,3 +17,4 @@
.Rproj.user
windows/
+docs
diff --git a/ci/conda_env_docs.txt b/r/adbcflightsql/_pkgdown.yml
similarity index 71%
copy from ci/conda_env_docs.txt
copy to r/adbcflightsql/_pkgdown.yml
index 105ea10a..4df7b75e 100644
--- a/ci/conda_env_docs.txt
+++ b/r/adbcflightsql/_pkgdown.yml
@@ -15,14 +15,16 @@
# specific language governing permissions and limitations
# under the License.
-breathe
-doxygen
-furo
-make
-numpydoc
-pytest
-sphinx>=5.0
-sphinx-autobuild
-sphinx-copybutton
-sphinx-design
-sphinxcontrib-mermaid
+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>
diff --git a/r/adbcflightsql/configure b/r/adbcflightsql/configure
index b1b58657..ef44e54d 100755
--- a/r/adbcflightsql/configure
+++ b/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"
diff --git a/r/adbcflightsql/src/Makevars.in b/r/adbcflightsql/src/Makevars.in
index dee44a7e..07423e73 100644
--- a/r/adbcflightsql/src/Makevars.in
+++ b/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@
diff --git a/r/adbcpostgresql/.Rbuildignore b/r/adbcpostgresql/.Rbuildignore
index 9e2a204e..70ce6665 100644
--- a/r/adbcpostgresql/.Rbuildignore
+++ b/r/adbcpostgresql/.Rbuildignore
@@ -10,3 +10,6 @@
^configure\.win$
^windows$
^\.vscode$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$
diff --git a/r/adbcpostgresql/.gitignore b/r/adbcpostgresql/.gitignore
index d025a1b1..11519d40 100644
--- a/r/adbcpostgresql/.gitignore
+++ b/r/adbcpostgresql/.gitignore
@@ -17,3 +17,4 @@
.Rproj.user
windows/
+docs
diff --git a/ci/conda_env_docs.txt b/r/adbcpostgresql/_pkgdown.yml
similarity index 71%
copy from ci/conda_env_docs.txt
copy to r/adbcpostgresql/_pkgdown.yml
index 105ea10a..4df7b75e 100644
--- a/ci/conda_env_docs.txt
+++ b/r/adbcpostgresql/_pkgdown.yml
@@ -15,14 +15,16 @@
# specific language governing permissions and limitations
# under the License.
-breathe
-doxygen
-furo
-make
-numpydoc
-pytest
-sphinx>=5.0
-sphinx-autobuild
-sphinx-copybutton
-sphinx-design
-sphinxcontrib-mermaid
+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>
diff --git a/r/adbcsnowflake/.Rbuildignore b/r/adbcsnowflake/.Rbuildignore
index 63632dd7..dcf011d1 100644
--- a/r/adbcsnowflake/.Rbuildignore
+++ b/r/adbcsnowflake/.Rbuildignore
@@ -7,3 +7,6 @@
^configure\.win$
^\.vscode$
^src/go/tmp$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$
diff --git a/r/adbcsnowflake/.gitignore b/r/adbcsnowflake/.gitignore
index d025a1b1..11519d40 100644
--- a/r/adbcsnowflake/.gitignore
+++ b/r/adbcsnowflake/.gitignore
@@ -17,3 +17,4 @@
.Rproj.user
windows/
+docs
diff --git a/ci/conda_env_docs.txt b/r/adbcsnowflake/_pkgdown.yml
similarity index 71%
copy from ci/conda_env_docs.txt
copy to r/adbcsnowflake/_pkgdown.yml
index 105ea10a..4df7b75e 100644
--- a/ci/conda_env_docs.txt
+++ b/r/adbcsnowflake/_pkgdown.yml
@@ -15,14 +15,16 @@
# specific language governing permissions and limitations
# under the License.
-breathe
-doxygen
-furo
-make
-numpydoc
-pytest
-sphinx>=5.0
-sphinx-autobuild
-sphinx-copybutton
-sphinx-design
-sphinxcontrib-mermaid
+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>
diff --git a/r/adbcsnowflake/configure b/r/adbcsnowflake/configure
index 2e917ab1..2f3ae664 100755
--- a/r/adbcsnowflake/configure
+++ b/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:"
diff --git a/r/adbcsqlite/.Rbuildignore b/r/adbcsqlite/.Rbuildignore
index e3a55b5e..e96b9e14 100644
--- a/r/adbcsqlite/.Rbuildignore
+++ b/r/adbcsqlite/.Rbuildignore
@@ -7,3 +7,6 @@
^src/sqlite3\.c$
^src/sqlite3\.h$
^\.vscode$
+^_pkgdown\.yml$
+^docs$
+^pkgdown$
diff --git a/r/adbcsqlite/.gitignore b/r/adbcsqlite/.gitignore
index 439ee9b1..0e0fe4a7 100644
--- a/r/adbcsqlite/.gitignore
+++ b/r/adbcsqlite/.gitignore
@@ -16,3 +16,4 @@
# under the License.
.Rproj.user
+docs
diff --git a/ci/conda_env_docs.txt b/r/adbcsqlite/_pkgdown.yml
similarity index 71%
copy from ci/conda_env_docs.txt
copy to r/adbcsqlite/_pkgdown.yml
index 105ea10a..4df7b75e 100644
--- a/ci/conda_env_docs.txt
+++ b/r/adbcsqlite/_pkgdown.yml
@@ -15,14 +15,16 @@
# specific language governing permissions and limitations
# under the License.
-breathe
-doxygen
-furo
-make
-numpydoc
-pytest
-sphinx>=5.0
-sphinx-autobuild
-sphinx-copybutton
-sphinx-design
-sphinxcontrib-mermaid
+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>
