This is an automated email from the ASF dual-hosted git repository.
kou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-erlang.git
The following commit(s) were added to refs/heads/main by this push:
new 7e26121 chore: Publish docs to arrow.apache.org (#68)
7e26121 is described below
commit 7e26121e7db24b2ba0a91ea76e2aabbef56b73b4
Author: Benjamin Philip <[email protected]>
AuthorDate: Wed Jul 8 12:55:01 2026 +0530
chore: Publish docs to arrow.apache.org (#68)
## What issue does this PR close?
Closes #55.
## What's changed
- Docs from main are served at https://arrow.apache.org/erlang/main/
- Released documentation is served at https://arrow.hexdocs.pm/
(currently
inactive till we release)
- Non-main paths at https://arrow.apache.org/erlang/ redirect to HexDocs
- Preview documentation on a pull request is served on the fork's GitHub
pages
- Duplicated workflows have been deleted
---
.github/workflows/docs.yml | 98 +++++++++++++++++++++++++++++++---------
.github/workflows/erlang-ci.yml | 43 ------------------
.github/workflows/pr_comment.yml | 54 ++++++++++++++++++++++
.htaccess | 20 ++++++++
CONTRIBUTING.md | 35 ++++++++++++++
5 files changed, 186 insertions(+), 64 deletions(-)
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index f4be4a7..8f8d8f7 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -15,34 +15,22 @@
# specific language governing permissions and limitations
# under the License.
-name: Generate Docs
+name: Docs CI
on:
push:
- branches:
- - main
- workflow_dispatch:
-
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
-permissions:
- contents: read
- pages: write
- id-token: write
+ pull_request:
-# Allow only one concurrent deployment
-concurrency:
- group: "pages"
- cancel-in-progress: true
+ workflow_dispatch:
env:
RUST_TOOLCHAIN_VERSION: stable
jobs:
- deploy:
+ build:
+ name: Build Docs
+ permissions:
+ contents: read
runs-on: ubuntu-latest
- environment:
- name: github-pages
- url: ${{ steps.deployment.outputs.page_url }}
-
steps:
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 #
v7.0.0
with:
@@ -85,8 +73,76 @@ jobs:
- name: Upload artifact
uses:
actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
+ name: docs-${{ github.sha }}
path: 'doc'
- - name: Deploy to GitHub Pages
- id: deployment
+ deploy_fork:
+ name: Deploy to GitHub Pages on fork
+ if: >-
+ (github.event_name == 'push' ||
+ github.event_name == 'workflow_dispatch') &&
+ github.repository != 'apache/arrow-erlang'
+ needs: build
+
+ # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+ permissions:
+ contents: read
+ pages: write
+ id-token: write
+
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+
+ # Allow only one concurrent deployment
+ concurrency:
+ group: "pages"
+ cancel-in-progress: true
+
+ runs-on: ubuntu-latest
+ steps:
+ - id: deployment
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 #
v5.0.0
+ with:
+ artifact_name: docs-${{ github.sha }}
+
+
+ asf_site:
+ # Only deploy on a push to main
+ if: github.ref_name == 'main' && github.event_name == 'push' &&
github.repository == 'apache/arrow-erlang'
+ name: Deploy to arrow.apache.org
+ needs: build
+
+ permissions:
+ contents: write
+
+ # Allow only one concurrent deployment
+ concurrency:
+ group: "asf_site"
+ cancel-in-progress: true
+
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 #
v7.0.0
+ with:
+ persist-credentials: false
+
+ - name: Download artifact
+ uses:
actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+ with:
+ name: docs-${{ github.sha }}
+ path: docs
+ - name: Prepare website
+ run: |
+ mkdir -p asf-site/main
+ tar -xf docs/artifact.tar -C asf-site/main
+ cp .asf.yaml asf-site
+ cp .htaccess asf-site
+ - name: Deploy to ASF
+ uses:
peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
+ with:
+ github_token: ${{ secrets.GITHUB_TOKEN }}
+ publish_dir: asf-site
+ publish_branch: asf-site
+ # Avoid accumulating history of in progress API jobs:
https://github.com/apache/arrow-rs/issues/5908
+ force_orphan: true
diff --git a/.github/workflows/erlang-ci.yml b/.github/workflows/erlang-ci.yml
index 9bb1e0d..3e04496 100644
--- a/.github/workflows/erlang-ci.yml
+++ b/.github/workflows/erlang-ci.yml
@@ -131,46 +131,3 @@ jobs:
- name: Run dialyzer
run: rebar3 dialyzer
-
- docbuild_test:
- name: Test Generate the Docs
- runs-on: ubuntu-latest
-
- steps:
- - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 #
v7.0.0
- with:
- persist-credentials: false
-
- - name: Cache Rust crates
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
- with:
- path: |
- ~/.cargo/bin/
- ~/.cargo/registry/index/
- ~/.cargo/registry/cache/
- ~/.cargo/git/db/
- key: test-native-${{ runner.os }}-${{ env.RUST_TOOLCHAIN_VERSION
}}-${{ hashFiles('native/**/Cargo.lock') }}
- restore-keys: |
- test-native-${{ runner.os }}-${{ env.RUST_TOOLCHAIN_VERSION }}
-
- - name: Install Rust
- uses: dtolnay/rust-toolchain@4be7066ada62dd38de10e7b70166bc74ed198c30
# stable
- with:
- toolchain: "${{ env.RUST_TOOLCHAIN_VERSION }}"
-
- - name: Install Erlang/OTP
- uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 #
v1.24.0
- with:
- otp-version: 25.1.0
- rebar3-version: '3.18.0'
-
- - name: Cache Hex packages
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
- with:
- path: ~/.cache/rebar3/hex/hexpm/packages
- key: ${{ runner.os }}-hex-${{ hashFiles(format('{0}{1}',
github.workspace, '/rebar.lock')) }}
- restore-keys: |
- ${{ runner.os }}-hex-
-
- - name: Generate Docs
- run: rebar3 ex_doc
diff --git a/.github/workflows/pr_comment.yml b/.github/workflows/pr_comment.yml
new file mode 100644
index 0000000..41403a5
--- /dev/null
+++ b/.github/workflows/pr_comment.yml
@@ -0,0 +1,54 @@
+# 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.
+
+name: PR comment
+
+on: # zizmor: ignore[dangerous-triggers]
+ pull_request_target:
+ types:
+ - opened
+
+permissions:
+ contents: read
+ issues: write
+ pull-requests: write
+
+jobs:
+ preview-url:
+ name: Preview URL
+ if: github.event.pull_request.head.repo.full_name != 'apache/arrow-erlang'
+ runs-on: ubuntu-latest
+ steps:
+ - name: Comment
+ env:
+ GH_TOKEN: ${{ github.token }}
+ PR_REPOSITORY: ${{ github.event.pull_request.base.repo.full_name }}
+ FORK_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
+ PR_NUMBER: ${{ github.event.number }}
+ run: |
+
configure_url="https://github.com/apache/arrow-erlang/blob/main/CONTRIBUTING.md#forks";
+ fork_owner=${FORK_REPOSITORY%/*}
+ fork_repository=${FORK_REPOSITORY#*/}
+ {
+ echo "Preview URL:
https://${fork_owner}.github.io/${fork_repository}";
+ echo ""
+ echo "If the preview URL doesn't work, you may forget to configure
your fork repository for preview."
+ echo "See ${configure_url} how to configure."
+ } | tee body.md
+ gh pr comment ${PR_NUMBER} \
+ --body-file body.md \
+ --repo ${PR_REPOSITORY}
diff --git a/.htaccess b/.htaccess
new file mode 100644
index 0000000..08bc1b5
--- /dev/null
+++ b/.htaccess
@@ -0,0 +1,20 @@
+# 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.
+
+ErrorDocument 404 /erlang/main/404.html
+
+RedirectMatch permanent ^/erlang/(?!main/?)(.*)$ https://arrow.hexdocs.pm/$1
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fa686e7..99c2fc6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -120,3 +120,38 @@ Please read our [development
documentation](https://arrow.apache.org/docs/developers/index.html) or
look through the [New Contributor's
Guide](https://arrow.apache.org/docs/developers/guide/index.html).
+
+### Forks
+
+We deploy a preview of the ExDoc documentation of any fork as a part of our
+tests.
+
+On a commit to all branches, the rendered static site will be
+published to GitHub Pages using GitHub Actions. The latest commit is
+only visible because all publications use the same url:
+https://${YOUR_GITHUB_ACCOUNT}.github.io/arrow-erlang/
+
+You need to configure your fork repository to use this feature:
+
+1. Enable GitHub Pages on your fork:
+ 1. Open
https://github.com/${YOUR_GITHUB_ACCOUNT}/arrow-erlang/settings/pages
+ 2. Select "GitHub Actions" as "Source"
+2. Accept publishing GitHub Pages from all branches on your fork:
+ 1. Open
https://github.com/${YOUR_GITHUB_ACCOUNT}/arrow-erlang/settings/environments
+ 2. Select the "github-pages" environment
+ 3. Change the default "Deployment branches and tags" rule:
+ 1. Press the "Edit" button
+ 2. Change the "Name pattern" to `*` from `main` or `gh-pages`
+
+See also the [GitHub Pages
+documentation](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow).
+
+
+FYI: You can also generate the site for https://arrow.apache.org/erlang/main
+to `doc/` locally by running the following:
+
+
+```shell
+rebar3 ex_doc
+```
+
