From 05fea1e0474ee2813ca590086fa03c735e29ef2e Mon Sep 17 00:00:00 2001 From: David Li Date: Mon, 5 Dec 2022 13:23:06 -0500 Subject: [PATCH 01/14] chore: publish docs to website --- .asf.yaml | 4 ++++ 1 file changed, 4 insertions(+) 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 From 257827927e02e84d7846df68b81e04375de69e55 Mon Sep 17 00:00:00 2001 From: David Li Date: Tue, 13 Dec 2022 13:53:05 -0500 Subject: [PATCH 02/14] Deploy to adbc/docs/ instead of adbc/ --- .asf.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.asf.yaml b/.asf.yaml index 8c532ef991..43abebef6c 100644 --- a/.asf.yaml +++ b/.asf.yaml @@ -32,4 +32,4 @@ notifications: publish: whoami: asf-site - subdir: adbc + subdir: adbc/docs From 895ab9f83490c51e386d052c26d3cae6e4b1dd28 Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 14 Dec 2022 09:24:58 -0500 Subject: [PATCH 03/14] Revert "Deploy to adbc/docs/ instead of adbc/" This reverts commit 7df3888249e9e40c2272819529c649e65315a721. --- .asf.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.asf.yaml b/.asf.yaml index 43abebef6c..8c532ef991 100644 --- a/.asf.yaml +++ b/.asf.yaml @@ -32,4 +32,4 @@ notifications: publish: whoami: asf-site - subdir: adbc/docs + subdir: adbc From bc5ed35ae7e02874da9058f4f6f329f1ea29620c Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 14 Dec 2022 09:36:52 -0500 Subject: [PATCH 04/14] Use versjon to generate redirect page --- .github/workflows/nightly-website.yml | 11 ++++++----- docs/source/conf.py | 2 ++ 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.github/workflows/nightly-website.yml b/.github/workflows/nightly-website.yml index 6084ea6cc1..20dcd1b6ca 100644 --- a/.github/workflows/nightly-website.yml +++ b/.github/workflows/nightly-website.yml @@ -59,15 +59,16 @@ jobs: uses: actions/download-artifact@v3 with: name: docs - path: dev + path: main - name: Build shell: bash run: | - ls -laR + pip install versjon + versjon + git add --force main/ index.html - 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/ + 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/docs/source/conf.py b/docs/source/conf.py index a43a3c278a..93937b794e 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 for versjon +version = release # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration From 57f936332d9152e4e2c52a36e4e3553217f817e0 Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 14 Dec 2022 09:55:33 -0500 Subject: [PATCH 05/14] Remove versjon --- .github/workflows/nightly-website.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/nightly-website.yml b/.github/workflows/nightly-website.yml index 20dcd1b6ca..5d93339217 100644 --- a/.github/workflows/nightly-website.yml +++ b/.github/workflows/nightly-website.yml @@ -63,9 +63,7 @@ jobs: - name: Build shell: bash run: | - pip install versjon - versjon - git add --force main/ index.html + git add --force main/ - name: Push changes to asf-site branch run: | git config --global user.name 'github-actions[bot]' From 9a56a969640eaa5803e474a0d06d5027e5e850f4 Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 14 Dec 2022 12:47:36 -0500 Subject: [PATCH 06/14] Add homegrown version switcher --- .github/workflows/nightly-website.yml | 8 ++- docs/source/_templates/base.html | 91 +++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 1 deletion(-) create mode 100644 docs/source/_templates/base.html diff --git a/.github/workflows/nightly-website.yml b/.github/workflows/nightly-website.yml index 5d93339217..17289c2d9c 100644 --- a/.github/workflows/nightly-website.yml +++ b/.github/workflows/nightly-website.yml @@ -63,7 +63,13 @@ jobs: - name: Build shell: bash run: | - git add --force main/ + pip install sphobjinv + rm -rf versions.txt + touch versions.txt + for inv in */objects.inv; do + echo "$(dirname $inv);$(sphobjinv convert json $inv - | jq -r .version)" >> versions.txt + done + git add --force main/ versions.txt - name: Push changes to asf-site branch run: | git config --global user.name 'github-actions[bot]' diff --git a/docs/source/_templates/base.html b/docs/source/_templates/base.html new file mode 100644 index 0000000000..3388dcfa78 --- /dev/null +++ b/docs/source/_templates/base.html @@ -0,0 +1,91 @@ +{# + 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 %} From b405d8572620415a9a2e17acf2089ccca9a5bffa Mon Sep 17 00:00:00 2001 From: David Li Date: Wed, 14 Dec 2022 14:48:24 -0500 Subject: [PATCH 07/14] Fix comment --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 93937b794e..8bfe87186a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -22,7 +22,7 @@ copyright = "2022, Apache Arrow Developers" author = "the Apache Arrow Developers" release = "0.1.0 (dev)" -# Needed for versjon +# Needed to generate version switcher version = release # -- General configuration --------------------------------------------------- From 42477361eb9e9b45c94b7cded3b04a1c9927c9b7 Mon Sep 17 00:00:00 2001 From: David Li Date: Thu, 15 Dec 2022 08:58:49 -0500 Subject: [PATCH 08/14] Copy version script at build time --- .github/workflows/nightly-website.yml | 17 +++-- ci/scripts/website_build.sh | 104 ++++++++++++++++++++++++++ docs/source/_static/version.js | 48 ++++++++++++ 3 files changed, 161 insertions(+), 8 deletions(-) create mode 100755 ci/scripts/website_build.sh create mode 100644 docs/source/_static/version.js diff --git a/.github/workflows/nightly-website.yml b/.github/workflows/nightly-website.yml index 17289c2d9c..250a1ef5e3 100644 --- a/.github/workflows/nightly-website.yml +++ b/.github/workflows/nightly-website.yml @@ -52,24 +52,25 @@ 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: main + path: temp - name: Build shell: bash run: | pip install sphobjinv - rm -rf versions.txt - touch versions.txt - for inv in */objects.inv; do - echo "$(dirname $inv);$(sphobjinv convert json $inv - | jq -r .version)" >> versions.txt - done - git add --force main/ versions.txt + ./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[bot]' diff --git a/ci/scripts/website_build.sh b/ci/scripts/website_build.sh new file mode 100755 index 0000000000..266a9d9677 --- /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 "${site}/${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..a4ad85bfce --- /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 + window.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); + }); +}); From c02ed5716c1a520f558af5a62769b68d10576166 Mon Sep 17 00:00:00 2001 From: David Li Date: Thu, 15 Dec 2022 09:04:23 -0500 Subject: [PATCH 09/14] Remove unused variable --- docs/source/_templates/base.html | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/source/_templates/base.html b/docs/source/_templates/base.html index 3388dcfa78..8bbbd46a65 100644 --- a/docs/source/_templates/base.html +++ b/docs/source/_templates/base.html @@ -25,7 +25,6 @@