Skip to content

Commit 7e26121

Browse files
Benjamin-PhilipBenjamin-Philip
authored
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
1 parent 1332724 commit 7e26121

5 files changed

Lines changed: 186 additions & 64 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 77 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -15,34 +15,22 @@
1515
# specific language governing permissions and limitations
1616
# under the License.
1717

18-
name: Generate Docs
18+
name: Docs CI
1919
on:
2020
push:
21-
branches:
22-
- main
23-
workflow_dispatch:
24-
25-
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
26-
permissions:
27-
contents: read
28-
pages: write
29-
id-token: write
21+
pull_request:
3022

31-
# Allow only one concurrent deployment
32-
concurrency:
33-
group: "pages"
34-
cancel-in-progress: true
23+
workflow_dispatch:
3524

3625
env:
3726
RUST_TOOLCHAIN_VERSION: stable
3827

3928
jobs:
40-
deploy:
29+
build:
30+
name: Build Docs
31+
permissions:
32+
contents: read
4133
runs-on: ubuntu-latest
42-
environment:
43-
name: github-pages
44-
url: ${{ steps.deployment.outputs.page_url }}
45-
4634
steps:
4735
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
4836
with:
@@ -85,8 +73,76 @@ jobs:
8573
- name: Upload artifact
8674
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
8775
with:
76+
name: docs-${{ github.sha }}
8877
path: 'doc'
8978

90-
- name: Deploy to GitHub Pages
91-
id: deployment
79+
deploy_fork:
80+
name: Deploy to GitHub Pages on fork
81+
if: >-
82+
(github.event_name == 'push' ||
83+
github.event_name == 'workflow_dispatch') &&
84+
github.repository != 'apache/arrow-erlang'
85+
needs: build
86+
87+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
88+
permissions:
89+
contents: read
90+
pages: write
91+
id-token: write
92+
93+
environment:
94+
name: github-pages
95+
url: ${{ steps.deployment.outputs.page_url }}
96+
97+
# Allow only one concurrent deployment
98+
concurrency:
99+
group: "pages"
100+
cancel-in-progress: true
101+
102+
runs-on: ubuntu-latest
103+
steps:
104+
- id: deployment
92105
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
106+
with:
107+
artifact_name: docs-${{ github.sha }}
108+
109+
110+
asf_site:
111+
# Only deploy on a push to main
112+
if: github.ref_name == 'main' && github.event_name == 'push' && github.repository == 'apache/arrow-erlang'
113+
name: Deploy to arrow.apache.org
114+
needs: build
115+
116+
permissions:
117+
contents: write
118+
119+
# Allow only one concurrent deployment
120+
concurrency:
121+
group: "asf_site"
122+
cancel-in-progress: true
123+
124+
runs-on: ubuntu-latest
125+
steps:
126+
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
127+
with:
128+
persist-credentials: false
129+
130+
- name: Download artifact
131+
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
132+
with:
133+
name: docs-${{ github.sha }}
134+
path: docs
135+
- name: Prepare website
136+
run: |
137+
mkdir -p asf-site/main
138+
tar -xf docs/artifact.tar -C asf-site/main
139+
cp .asf.yaml asf-site
140+
cp .htaccess asf-site
141+
- name: Deploy to ASF
142+
uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
143+
with:
144+
github_token: ${{ secrets.GITHUB_TOKEN }}
145+
publish_dir: asf-site
146+
publish_branch: asf-site
147+
# Avoid accumulating history of in progress API jobs: https://github.com/apache/arrow-rs/issues/5908
148+
force_orphan: true

‎.github/workflows/erlang-ci.yml‎

Lines changed: 0 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -131,46 +131,3 @@ jobs:
131131

132132
- name: Run dialyzer
133133
run: rebar3 dialyzer
134-
135-
docbuild_test:
136-
name: Test Generate the Docs
137-
runs-on: ubuntu-latest
138-
139-
steps:
140-
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
141-
with:
142-
persist-credentials: false
143-
144-
- name: Cache Rust crates
145-
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
146-
with:
147-
path: |
148-
~/.cargo/bin/
149-
~/.cargo/registry/index/
150-
~/.cargo/registry/cache/
151-
~/.cargo/git/db/
152-
key: test-native-${{ runner.os }}-${{ env.RUST_TOOLCHAIN_VERSION }}-${{ hashFiles('native/**/Cargo.lock') }}
153-
restore-keys: |
154-
test-native-${{ runner.os }}-${{ env.RUST_TOOLCHAIN_VERSION }}
155-
156-
- name: Install Rust
157-
uses: dtolnay/rust-toolchain@4be7066ada62dd38de10e7b70166bc74ed198c30 # stable
158-
with:
159-
toolchain: "${{ env.RUST_TOOLCHAIN_VERSION }}"
160-
161-
- name: Install Erlang/OTP
162-
uses: erlef/setup-beam@fc68ffb90438ef2936bbb3251622353b3dcb2f93 # v1.24.0
163-
with:
164-
otp-version: 25.1.0
165-
rebar3-version: '3.18.0'
166-
167-
- name: Cache Hex packages
168-
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
169-
with:
170-
path: ~/.cache/rebar3/hex/hexpm/packages
171-
key: ${{ runner.os }}-hex-${{ hashFiles(format('{0}{1}', github.workspace, '/rebar.lock')) }}
172-
restore-keys: |
173-
${{ runner.os }}-hex-
174-
175-
- name: Generate Docs
176-
run: rebar3 ex_doc

‎.github/workflows/pr_comment.yml‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
name: PR comment
19+
20+
on: # zizmor: ignore[dangerous-triggers]
21+
pull_request_target:
22+
types:
23+
- opened
24+
25+
permissions:
26+
contents: read
27+
issues: write
28+
pull-requests: write
29+
30+
jobs:
31+
preview-url:
32+
name: Preview URL
33+
if: github.event.pull_request.head.repo.full_name != 'apache/arrow-erlang'
34+
runs-on: ubuntu-latest
35+
steps:
36+
- name: Comment
37+
env:
38+
GH_TOKEN: ${{ github.token }}
39+
PR_REPOSITORY: ${{ github.event.pull_request.base.repo.full_name }}
40+
FORK_REPOSITORY: ${{ github.event.pull_request.head.repo.full_name }}
41+
PR_NUMBER: ${{ github.event.number }}
42+
run: |
43+
configure_url="https://github.com/apache/arrow-erlang/blob/main/CONTRIBUTING.md#forks"
44+
fork_owner=${FORK_REPOSITORY%/*}
45+
fork_repository=${FORK_REPOSITORY#*/}
46+
{
47+
echo "Preview URL: https://${fork_owner}.github.io/${fork_repository}"
48+
echo ""
49+
echo "If the preview URL doesn't work, you may forget to configure your fork repository for preview."
50+
echo "See ${configure_url} how to configure."
51+
} | tee body.md
52+
gh pr comment ${PR_NUMBER} \
53+
--body-file body.md \
54+
--repo ${PR_REPOSITORY}

‎.htaccess‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Licensed to the Apache Software Foundation (ASF) under one
2+
# or more contributor license agreements. See the NOTICE file
3+
# distributed with this work for additional information
4+
# regarding copyright ownership. The ASF licenses this file
5+
# to you under the Apache License, Version 2.0 (the
6+
# "License"); you may not use this file except in compliance
7+
# with the License. You may obtain a copy of the License at
8+
#
9+
# http://www.apache.org/licenses/LICENSE-2.0
10+
#
11+
# Unless required by applicable law or agreed to in writing,
12+
# software distributed under the License is distributed on an
13+
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14+
# KIND, either express or implied. See the License for the
15+
# specific language governing permissions and limitations
16+
# under the License.
17+
18+
ErrorDocument 404 /erlang/main/404.html
19+
20+
RedirectMatch permanent ^/erlang/(?!main/?)(.*)$ https://arrow.hexdocs.pm/$1

‎CONTRIBUTING.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,3 +120,38 @@ Please read our [development
120120
documentation](https://arrow.apache.org/docs/developers/index.html) or
121121
look through the [New Contributor's
122122
Guide](https://arrow.apache.org/docs/developers/guide/index.html).
123+
124+
### Forks
125+
126+
We deploy a preview of the ExDoc documentation of any fork as a part of our
127+
tests.
128+
129+
On a commit to all branches, the rendered static site will be
130+
published to GitHub Pages using GitHub Actions. The latest commit is
131+
only visible because all publications use the same url:
132+
https://${YOUR_GITHUB_ACCOUNT}.github.io/arrow-erlang/
133+
134+
You need to configure your fork repository to use this feature:
135+
136+
1. Enable GitHub Pages on your fork:
137+
1. Open https://github.com/${YOUR_GITHUB_ACCOUNT}/arrow-erlang/settings/pages
138+
2. Select "GitHub Actions" as "Source"
139+
2. Accept publishing GitHub Pages from all branches on your fork:
140+
1. Open https://github.com/${YOUR_GITHUB_ACCOUNT}/arrow-erlang/settings/environments
141+
2. Select the "github-pages" environment
142+
3. Change the default "Deployment branches and tags" rule:
143+
1. Press the "Edit" button
144+
2. Change the "Name pattern" to `*` from `main` or `gh-pages`
145+
146+
See also the [GitHub Pages
147+
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).
148+
149+
150+
FYI: You can also generate the site for https://arrow.apache.org/erlang/main
151+
to `doc/` locally by running the following:
152+
153+
154+
```shell
155+
rebar3 ex_doc
156+
```
157+

0 commit comments

Comments
 (0)