chore: publish docs to website

.asf.yaml

@@ -29,3 +29,7 @@ notifications:
   issues:       github@arrow.apache.org
   pullrequests: github@arrow.apache.org
   jira_options: link label worklog
+
+publish:
+  whoami: asf-site
+  subdir: adbc

.github/workflows/nightly-website.yml

@@ -21,8 +21,15 @@ on:
   push:
     branches:
       - main
+    tags:
+      - 'apache-arrow-adbc-*'
   workflow_dispatch: {}
 
+# Ensure concurrent builds don't stomp on each other
+concurrency:
+  group: ${{ github.repository }}-${{ github.workflow }}
+  cancel-in-progress: false
+
 jobs:
   build:
     name: "Build Website"
@@ -52,22 +59,29 @@ jobs:
       - uses: actions/checkout@v3
         with:
           fetch-depth: 0
+          path: site
           # NOTE: needed to push at the end
           persist-credentials: true
           ref: asf-site
-      - name: Add dev docs
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          path: scripts
+          persist-credentials: false
+      - name: Download docs
         uses: actions/download-artifact@v3
         with:
           name: docs
-          path: dev
+          path: temp
       - name: Build
         shell: bash
         run: |
-          ls -laR
+          pip install sphobjinv
+          ./scripts/ci/scripts/website_build.sh "$(pwd)/scripts" "$(pwd)/site" "$(pwd)/temp"
       - name: Push changes to asf-site branch
         run: |
-          git config --global user.name 'GitHub Actions'
-          git config --global user.email 'actions@github.com'
-          git add --force dev/
+          cd site
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
           git commit -m "publish documentation" --allow-empty
           git push origin asf-site:asf-site

ci/scripts/website_build.sh

@@ -0,0 +1,104 @@
+#!/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.
+
+# Regenerate the versions.txt used to power the version switcher in
+# the docs
+# Assumes sphobjinv is installed (pip)
+
+set -e
+set -o pipefail
+set -u
+set -x
+
+main() {
+    if [[ "$#" != 3 ]]; then
+       echo "Usage: ${0} <adbc-checkout> <asf-site-checkout> <new-docs-path>"
+       exit 1
+    fi
+    # Path to ADBC repo
+    local -r repo="${1}"
+    # Path to ADBC repo, asf-site branch
+    local -r site="${2}"
+    # The path to the newly generated docs
+    local -r docs="${3}"
+
+    # Determine path for new docs
+
+    local -r new_version=$(sphobjinv convert json "${docs}/objects.inv" - | jq -r .version)
+    if [[ -z "${new_version}" ]]; then
+        echo "Could not determine version of generated docs"
+        exit 1
+    fi
+
+    local -r regex='^([0-9]+\.[0-9]+\.[0-9]+)$'
+    if [[ "${new_version}" =~ $regex ]]; then
+        cp -r "${docs}" "${site}/${new_version}"
+        git -C "${site}" add --force "${new_version}"
+    else
+        # Assume this is dev docs
+        rm -rf "${site}/main"
+        cp -r "${docs}" "${site}/main"
+        git -C "${site}" add --force "main"
+    fi
+
+    # Copy the version script and regenerate the version list
+    # The versions get embedded into the JavaScript file to save a roundtrip
+    rm -f "${site}/version.js"
+    cp "${repo}/docs/source/_static/version.js" "${site}/version.js"
+    echo >> "${site}/version.js"
+    echo 'const versions = `' >> "${site}/version.js"
+
+    pushd "${site}"
+    for inv in */objects.inv; do
+        echo "$(dirname $inv);$(sphobjinv convert json $inv - | jq -r .version)"
+    done | sort -t ";" --version-sort | tee --append "${site}/version.js" "${site}/versions.txt"
+    popd
+
+    echo '`;' >> "${site}/version.js"
+    git -C "${site}" add -f "version.js"
+
+    # Determine the latest stable version
+    local -r latest_docs=$(grep -E ';[0-9]+\.[0-9]+\.[0-9]+$' "${site}/versions.txt" | sort -t ';' --version-sort | tail -n1)
+    if [[ -z "${latest_docs}" ]]; then
+        echo "No stable versions found"
+        local -r latest_dir="main"
+        local -r latest_version="${new_version}"
+    else
+        local -r latest_dir=$(echo "${latest_docs}" | awk -F';' '{print $1}')
+        local -r latest_version=$(echo "${latest_docs}" | awk -F';' '{print $2}')
+    fi
+    echo "Latest version: ${latest_version} in directory ${latest_dir}"
+
+    # Generate index.html
+    cat > "${site}/index.html" << EOF
+<!DOCTYPE html>
+<meta http-equiv="Refresh" content="0; url=$latest_dir/index.html">
+EOF
+    git -C "${site}" add -f "index.html"
+
+    # Generate latest/index.html
+    mkdir -p "${site}/latest"
+    cat > "${site}/latest/index.html" << EOF
+<!DOCTYPE html>
+<meta http-equiv="Refresh" content="0; url=../$latest_dir/index.html">
+EOF
+    git -C "${site}" add -f "latest/index.html"
+}
+
+main "$@"

docs/source/_static/version.js

@@ -0,0 +1,48 @@
+// 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.
+
+// Generate a version switcher on the fly.  This is actually meant to
+// be loaded from the website root (arrow.apache.org/adbc/version.js)
+// and not from the documentation subdirectory itself.  This lets us
+// update the script globally.  It depends on certain variables being
+// injected into the Sphinx template.
+
+window.addEventListener("DOMContentLoaded", () => {
+    // The template should contain this list, we just populate it
+    const root = document.querySelector("#version-switcher ul");
+
+    // Variable injected by ci/scripts/website_build.sh
+    // Format:
+    // path;version\npath2;version2;\n...
+    // Versions are sorted at generation time
+    versions
+        .trim()
+        .split(/\n/g)
+        .map((version) => version.split(/;/))
+        .forEach((version) => {
+            const el = document.createElement("a");
+            // Variable injected by template
+            el.setAttribute("href", versionsRoot + "/" + version[0]);
+            el.innerText = version[1];
+            if (version[1] === currentVersion) {
+                el.classList.toggle("active");
+            }
+            const li = document.createElement("li");
+            li.appendChild(el);
+            root.appendChild(li);
+        });
+});

docs/source/_templates/base.html

@@ -0,0 +1,90 @@
+{#
+ 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.
+#}
+
+{% extends "furo/base.html" %}
+
+{% set rel_docs_top = pagename.split('/') | map(attribute='notfound', default='..') | join('/') %}
+
+{% block extrahead %}
+<script>
+  const currentVersion = "{{ version }}";
+  const versionsRoot = "{{ rel_docs_top }}";
+</script>
+<style>
+  #version-switcher {
+    background: var(--color-background-primary);
+    bottom: 2em;
+    box-shadow: 0 .1rem .25rem var(--sd-color-shadow),0 0 .0625rem rgba(0,0,0,.1);
+    position: fixed;
+    right: 2em;
+    z-index: 9999;
+  }
+
+  #version-switcher button {
+    background-color: var(--sd-color-card-header);
+    border: 0;
+    color: var(--sd-color-card-text);
+    cursor: pointer;
+    font-family: var(--font-stack);
+    padding: 0.5em;
+    width: 100%;
+  }
+
+  #version-switcher button::after {
+    content: "▼";
+  }
+
+  #version-switcher.open button::after {
+    content: "▲";
+  }
+
+  #version-switcher div.versions {
+    height: 0;
+    overflow-y: hidden;
+    padding: 0 0.5em;
+    transition: all 0.2s ease-in;
+  }
+
+  #version-switcher.open div.versions {
+    height: 8em;
+    overflow-y: scroll;
+  }
+
+  #version-switcher .active {
+    font-weight: bold;
+  }
+</style>
+{% endblock %}
+
+{# Inject skeleton of version switcher #}
+{% block body -%}
+{{ super() }}
+<nav id="version-switcher">
+  <button type="button" onclick="document.getElementById('version-switcher').classList.toggle('open')">Version: {{ version }}</button>
+  <div class="versions">
+    <ul></ul>
+  </div>
+</nav>
+{%- endblock %}
+
+{# Inject relative script - this should resolve to https://arrow.apache.org/adbc/version.js #}
+{% block scripts -%}
+{{ super() }}
+<script async defer src="{{ rel_docs_top }}/version.js"></script>
+{%- endblock %}

docs/source/conf.py

@@ -22,6 +22,8 @@
 copyright = "2022, Apache Arrow Developers"
 author = "the Apache Arrow Developers"
 release = "0.1.0 (dev)"
+# Needed to generate version switcher
+version = release
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration