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 +``` +