diff --git a/.asf.yaml b/.asf.yaml index 4d159b772e..8c532ef991 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 6084ea6cc1..2b2679c381 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 0000000000..b80338d813 --- /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} " + 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 + + +EOF + git -C "${site}" add -f "index.html" + + # Generate latest/index.html + mkdir -p "${site}/latest" + cat > "${site}/latest/index.html" << EOF + + +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 0000000000..0f63def9f3 --- /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 0000000000..8bbbd46a65 --- /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 %} + + +{% endblock %} + +{# Inject skeleton of version switcher #} +{% block body -%} +{{ super() }} + +{%- endblock %} + +{# Inject relative script - this should resolve to https://arrow.apache.org/adbc/version.js #} +{% block scripts -%} +{{ super() }} + +{%- endblock %} diff --git a/docs/source/conf.py b/docs/source/conf.py index a43a3c278a..8bfe87186a 100644 --- a/docs/source/conf.py +++ b/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