chore: Publish docs to arrow.apache.org

.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,75 @@ 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: |
+          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

.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

.github/workflows/pr_comment.yml

@@ -0,0 +1,53 @@
+# 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
+    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}

.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

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/arrow-erlang/main
+to `doc/` locally by running the following:
+
+
+```shell
+rebar3 ex_doc
+```
+