You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@arrow.apache.org by li...@apache.org on 2022/12/15 21:27:17 UTC
[arrow-adbc] branch main updated: chore: publish docs to website (#218)
This is an automated email from the ASF dual-hosted git repository.
lidavidm 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 6507ebe chore: publish docs to website (#218)
6507ebe is described below
commit 6507ebe96ecb99df60c2814d60eb937a35c41437
Author: David Li <li...@gmail.com>
AuthorDate: Thu Dec 15 16:27:12 2022 -0500
chore: publish docs to website (#218)
---
.asf.yaml | 4 ++
.github/workflows/nightly-website.yml | 26 +++++++--
ci/scripts/website_build.sh | 104 ++++++++++++++++++++++++++++++++++
docs/source/_static/version.js | 48 ++++++++++++++++
docs/source/_templates/base.html | 90 +++++++++++++++++++++++++++++
docs/source/conf.py | 2 +
6 files changed, 268 insertions(+), 6 deletions(-)
diff --git a/.asf.yaml b/.asf.yaml
index 4d159b7..8c532ef 100644
--- a/.asf.yaml
+++ b/.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
diff --git a/.github/workflows/nightly-website.yml b/.github/workflows/nightly-website.yml
index 6084ea6..2b2679c 100644
--- a/.github/workflows/nightly-website.yml
+++ b/.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
diff --git a/ci/scripts/website_build.sh b/ci/scripts/website_build.sh
new file mode 100755
index 0000000..b80338d
--- /dev/null
+++ b/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 "$@"
diff --git a/docs/source/_static/version.js b/docs/source/_static/version.js
new file mode 100644
index 0000000..0f63def
--- /dev/null
+++ b/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);
+ });
+});
diff --git a/docs/source/_templates/base.html b/docs/source/_templates/base.html
new file mode 100644
index 0000000..8bbbd46
--- /dev/null
+++ b/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 %}
diff --git a/docs/source/conf.py b/docs/source/conf.py
index a43a3c2..8bfe871 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -22,6 +22,8 @@ project = "ADBC"
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