Skip to content

Commit 2cc19c0

Browse files
koukou
committed
chore: Publish docs
1 parent cbf0998 commit 2cc19c0

File tree

5 files changed

+228
-9
lines changed

5 files changed

+228
-9
lines changed

‎.github/workflows/rc.yaml

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,75 @@ jobs:
8787
run: |
8888
dev/release/run_rat.sh "${TAR_GZ}"
8989
90+
docs:
91+
name: Documentation
92+
needs: target
93+
runs-on: ubuntu-latest
94+
timeout-minutes: 5
95+
permissions:
96+
contents: write
97+
env:
98+
RC: ${{ needs.target.outputs.rc }}
99+
VERSION: ${{ needs.target.outputs.version }}
100+
steps:
101+
- name: Checkout
102+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
103+
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
104+
with:
105+
cache: yarn
106+
node-version: 20
107+
- name: Install dependencies
108+
run: |
109+
yarn install
110+
- name: Build
111+
run: |
112+
yarn doc
113+
- name: Package
114+
run: |
115+
id="apache-arrow-js-docs-${VERSION}"
116+
tar_gz="${id}.tar.gz"
117+
mv doc "${id}"
118+
tar czf "${tar_gz}" "${id}"
119+
sha256sum "${tar_gz}" > "${tar_gz}.sha256"
120+
sha512sum "${tar_gz}" > "${tar_gz}.sha512"
121+
- name: Upload
122+
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
123+
with:
124+
name: release-docs
125+
path: |
126+
apache-arrow-js-docs-*.tar.gz*
127+
- name: Prepare for publish
128+
run: |
129+
need_publish=no
130+
branch=
131+
if [ "${GITHUB_EVENT_NAME}" = "push" ]; then
132+
if [ "${GITHUB_REPOSITORY}" = "apache/arrow-js" ]; then
133+
branch=asf-site
134+
if [ "${GITHUB_REF_NAME}" = "main" ]; then
135+
need_publish=yes
136+
fi
137+
else
138+
branch=gh-pages
139+
need_publish=yes
140+
fi
141+
fi
142+
if [ "${need_publish}" = "yes" ]; then
143+
ci/scripts/update_docs.sh "${VERSION}" "${branch}"
144+
fi
145+
echo "NEED_PUBLISH=${need_publish}" >> "${GITHUB_ENV}"
146+
- name: Publish
147+
if: env.NEED_PUBLISH == 'yes'
148+
run: |
149+
cd site
150+
cp -a ../.asf.yaml ./
151+
git add .asf.yaml
152+
git config user.name "github-actions[bot]"
153+
git config user.email "github-actions[bot]@users.noreply.github.com"
154+
if [ "$(git diff --cached)" != "" ]; then
155+
git commit -m "Update ${GITHUB_SHA}"
156+
git push origin "$(git branch --show-current)"
157+
fi
158+
90159
packages:
91160
name: Packages
92161
runs-on: ubuntu-latest
@@ -153,6 +222,7 @@ jobs:
153222
upload:
154223
name: Upload
155224
needs:
225+
- docs
156226
- target
157227
- verify
158228
runs-on: ubuntu-latest

‎.github/workflows/release.yaml

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,31 @@ jobs:
5656
--title "Apache Arrow JS ${version}" \
5757
--verify-tag \
5858
dists/*
59+
- name: Checkout asf-site
60+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
61+
with:
62+
ref: asf-site
63+
path: site
64+
- name: Update documentation
65+
run: |
66+
version=${GITHUB_REF_NAME#v}
67+
tar_gz=${PWD}/dists/apache-arrow-js-docs-${version}.tar.gz
68+
69+
pushd site
70+
71+
rm -rf current
72+
mkdir -p current
73+
pushd current
74+
tar xf "${tar_gz}" --strip-components=1
75+
popd
76+
git add current
77+
78+
rm -rf "${version}"
79+
cp -a current "${version}"
80+
git add "${version}"
81+
82+
git config user.name "github-actions[bot]"
83+
git config user.email "github-actions[bot]@users.noreply.github.com"
84+
85+
git commit -m "Update docs for ${version}"
86+
git push origin "$(git branch --show-current)"

‎DEVELOP.md

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,9 @@
1717
under the License.
1818
-->
1919

20-
# Getting Involved
20+
# How to develop
21+
22+
## Getting Involved
2123

2224
Even if you do not plan to contribute to Apache Arrow itself or Arrow
2325
integrations in other projects, we'd be happy to have you involved:
@@ -40,7 +42,7 @@ If you’d like to report a bug but don’t have time to fix it, you can still p
4042
it on GitHub issues, or email the mailing list
4143
[[email protected]](http://mail-archives.apache.org/mod_mbox/arrow-dev/)
4244

43-
# The package.json scripts
45+
## The package.json scripts
4446

4547
We use [yarn](https://yarnpkg.com/) to install dependencies and run scrips.
4648

@@ -70,19 +72,19 @@ To run tests directly on the sources without bundling, use the `src` target (e.g
7072

7173
Compiles the documentation with [Typedoc](https://typedoc.org/). Use `yarn doc --watch` to automatically rebuild when the docs change.
7274

73-
# Running the Performance Benchmarks
75+
## Running the Performance Benchmarks
7476

7577
You can run the benchmarks with `yarn perf`. To print the results to stderr as JSON, add the `--json` flag (e.g. `yarn perf --json 2> perf.json`).
7678

7779
You can change the target you want to test by changing the imports in `perf/index.ts`. Note that you need to compile the bundles with `yarn build` before you can import them.
7880

79-
# Testing Bundling
81+
## Testing Bundling
8082

8183
The bundles use `apache-arrow` so make sure to build it with `yarn build -t apache-arrow`. To bundle with a variety of bundlers, run `yarn test:bundle` or `yarn gulp bundle`.
8284

8385
Run `yarn gulp bundle:webpack:analyze` to open [Webpack Bundle Analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer).
8486

85-
# Updating the Arrow format flatbuffers generated code
87+
## Updating the Arrow format flatbuffers generated code
8688

8789
1. Once generated, the flatbuffers format code needs to be adjusted for our build scripts (assumes `gnu-sed`):
8890

@@ -110,6 +112,25 @@ Run `yarn gulp bundle:webpack:analyze` to open [Webpack Bundle Analyzer](https:/
110112
111113
4. Execute `yarn lint` from the `js` directory to fix the linting errors
112114
115+
## How to preview documentation on your fork repository
116+
117+
Our GitHub Actions workflows will create the `gh-pages` branch on your
118+
fork repository automatically. It's for previewing documentation with
119+
your changes in a branch.
120+
121+
You need to enable GitHub Pages on your fork repository at
122+
`https://github.com/${YOUR_GITHUB_ID}/arrow-js/settings/pages`
123+
manually. Choose the `gh-pages` branch in the "Build and deploy" ->
124+
"Branch" configuration item and press the "Save" button. We can
125+
preview documentation by GitHub Pages for your fork repository:
126+
`https://${YOUR_GITHUB_ID}.github.io/arrow-js/`
127+
128+
Example: https://kou.github.io/arrow-js/
129+
130+
The `gh-pages` branch keeps previews of all branches. We recommend
131+
that you delete needless branches and merged branches from your fork.
132+
133+
113134
[1]: mailto:[email protected]
114135
[2]: https://github.com/apache/arrow/tree/main/format
115136
[3]: https://github.com/apache/arrow-js/issues

‎ci/scripts/update_docs.sh

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
#!/usr/bin/env bash
2+
#
3+
# Licensed to the Apache Software Foundation (ASF) under one
4+
# or more contributor license agreements. See the NOTICE file
5+
# distributed with this work for additional information
6+
# regarding copyright ownership. The ASF licenses this file
7+
# to you under the Apache License, Version 2.0 (the
8+
# "License"); you may not use this file except in compliance
9+
# with the License. You may obtain a copy of the License at
10+
#
11+
# http://www.apache.org/licenses/LICENSE-2.0
12+
#
13+
# Unless required by applicable law or agreed to in writing,
14+
# software distributed under the License is distributed on an
15+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16+
# KIND, either express or implied. See the License for the
17+
# specific language governing permissions and limitations
18+
# under the License.
19+
20+
set -exu
21+
22+
version="${1}"
23+
target_branch="${2}"
24+
25+
html_escape() {
26+
# & -> & must be the first substitution
27+
sed -e "s/&/&/g" \
28+
-e "s/</&lt;/g" \
29+
-e "s/>/&gt;/g" \
30+
-e "s/\"/&quot;/g" \
31+
-e "s/'/&apos;/g"
32+
}
33+
34+
if ! git fetch origin "${target_branch}"; then
35+
git worktree add --orphan -b "${target_branch}" site
36+
else
37+
git worktree add site "origin/${target_branch}"
38+
fi
39+
40+
tar_gz="${PWD}/apache-arrow-js-docs-${version}.tar.gz"
41+
42+
extract_docs() {
43+
local destination="${1}"
44+
45+
rm -rf "${destination}"
46+
mkdir -p "${destination}"
47+
pushd "${destination}"
48+
tar xf "${tar_gz}" --strip-components=1
49+
popd
50+
git add "${destination}"
51+
}
52+
53+
pushd site
54+
if [ "${target_branch}" = "asf-site" ]; then
55+
# Update https://arrow.apache.org/js/main/
56+
extract_docs main
57+
58+
# Create .htaccess
59+
cat >.htaccess <<HTACCESS
60+
RedirectMatch "^/js/$" "/js/current/"
61+
HTACCESS
62+
git add .htaccess
63+
else
64+
# Remove data for nonexistent branches
65+
for branch in *; do
66+
if [ ! -d "${branch}" ]; then
67+
continue
68+
fi
69+
if ! git fetch origin "${branch}"; then
70+
git rm "${branch}"
71+
fi
72+
done
73+
74+
# Update the pushed branch
75+
extract_docs "${GITHUB_REF_NAME}"
76+
77+
# Create index.html
78+
{
79+
echo "<!DOCTYPE html>"
80+
echo "<html>"
81+
echo " <head>"
82+
echo " <title>Apache Arrow JS documents</title>"
83+
echo " </head>"
84+
echo " <body>"
85+
echo " <ul>"
86+
for branch in *; do
87+
if [ ! -d "${branch}" ]; then
88+
continue
89+
fi
90+
escaped_branch="$(echo "${branch}" | html_escape)"
91+
echo " <li>"
92+
echo " <a href=\"${escaped_branch}/\">${escaped_branch}</a>"
93+
echo " </li>"
94+
done
95+
echo " </ul>"
96+
echo " </body>"
97+
echo "</html>"
98+
} >index.html
99+
git add index.html
100+
fi
101+
popd

‎dev/release/release_rc.sh

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -78,12 +78,11 @@ rc_hash="$(git rev-list --max-count=1 "${rc_tag}")"
7878

7979
artifacts_dir="apache-arrow-js-${version}-rc${rc}"
8080
signed_artifacts_dir="${artifacts_dir}-signed"
81+
git_origin_url="$(git remote get-url origin)"
82+
repository="${git_origin_url#*github.com?}"
83+
repository="${repository%.git}"
8184

8285
if [ "${RELEASE_SIGN}" -gt 0 ]; then
83-
git_origin_url="$(git remote get-url origin)"
84-
repository="${git_origin_url#*github.com?}"
85-
repository="${repository%.git}"
86-
8786
echo "Looking for GitHub Actions workflow on ${repository}:${rc_tag}"
8887
run_id=""
8988
while true; do

0 commit comments

Comments
 (0)