Skip to content

Commit 6410f35

Browse files
ilyagrilyagr
committed
docs: define github actions
One action publishes the 'prerelease' version on every push to `main`. The other publishes a 'latest' version on every releasse. I tested both of them, but not with branch protection rules.
1 parent cc31024 commit 6410f35

File tree

4 files changed

+142
-1
lines changed

4 files changed

+142
-1
lines changed

‎.github/scripts/docs-build-deploy

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
#!/bin/sh
2+
# Set up a virtual environment with the required tools, build, and deploy the docs.
3+
#
4+
# Run from the root directory of the project as
5+
# .github/scripts/docs-build-deploy 'https://martinvonz.github.io' prerelease main
6+
# All arguments after the first are passed to `mike deploy`, run
7+
# `poetry run -- mike deploy --help` for options. Note that `mike deploy`
8+
# creates a commit directly on the `gh-pages` branch.
9+
set -ev
10+
11+
export "SITE_URL_FOR_MKDOCS=$1"; shift
12+
# https://github.com/python-poetry/poetry/issues/1917
13+
export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring
14+
poetry install # Only really needed once per environment unless there are updates
15+
poetry run -- mike deploy "$@"

‎.github/workflows/docs.yml

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: website
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
prerelease-docs-build-deploy:
13+
strategy:
14+
matrix:
15+
os: [ubuntu-latest]
16+
runs-on: ${{ matrix.os }}
17+
18+
steps:
19+
- uses: actions/checkout@v3
20+
- run: "git fetch origin gh-pages --depth=1"
21+
- uses: actions/setup-python@v4
22+
with:
23+
python-version: 3.11
24+
- name: Install poetry
25+
uses: abatilo/actions-poetry@v2
26+
with:
27+
poetry-version: latest
28+
- name: Install dependencies, compile and deploy docs
29+
run: |
30+
git config user.name jj-docs-bot
31+
git config user.email [email protected]
32+
.github/scripts/docs-build-deploy 'https://martinvonz.github.io/jj' prerelease main --push
33+
- name: "Show `git diff --stat`"
34+
run: git diff --stat gh-pages^ gh-pages || echo "(No diffs)"

‎.github/workflows/release.yml

+28
Original file line numberDiff line numberDiff line change
@@ -70,3 +70,31 @@ jobs:
7070
asset_path: ${{ env.ASSET }}
7171
asset_name: ${{ env.ASSET }}
7272
asset_content_type: application/octet-stream
73+
74+
docs-build-deploy:
75+
strategy:
76+
matrix:
77+
os: [ubuntu-latest]
78+
runs-on: ${{ matrix.os }}
79+
permissions:
80+
contents: write
81+
82+
steps:
83+
- uses: actions/checkout@v3
84+
- run: "git fetch origin gh-pages --depth=1"
85+
- uses: actions/setup-python@v4
86+
with:
87+
python-version: 3.11
88+
- name: Install poetry
89+
uses: abatilo/actions-poetry@v2
90+
with:
91+
poetry-version: latest
92+
- name: Install dependencies, compile and deploy docs
93+
run: |
94+
git config user.name jj-docs-bot
95+
git config user.email [email protected]
96+
# Using the 'latest' tag below makes the website default
97+
# to this version.
98+
.github/scripts/docs-build-deploy 'https://martinvonz.github.io/jj' "${{ github.event.release.tag_name }}" latest --update-aliases --push
99+
- name: "Show `git diff --stat`"
100+
run: git diff --stat gh-pages^ gh-pages || echo "(No diffs)"

‎docs/contributing.md

+65-1
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,12 @@ These are listed roughly in order of decreasing importance.
136136

137137
## Previewing the HTML documentation
138138

139-
<!---- Short-term TODO: More docs follow in a subsequent commit ---->
139+
The documentation for `jj` is automatically published to the website
140+
<https://martinvonz.github.io/jj/>. At the moment, this is experimental,
141+
but we hope to advertise this website to our users soon.
142+
143+
When editing documentation, we'd appreciate it if you checked that the
144+
result will look as expected when published to the website.
140145

141146
### Setting up the prerequisites
142147

@@ -184,6 +189,65 @@ occasionally check the terminal from which you ran `mkdocs serve` for
184189
any build errors or warnings. Warnings about
185190
`"GET /versions.json HTTP/1.1" code 404` are expected and harmless.
186191

192+
### How to build the entire website (not usually necessary)
193+
194+
The full `jj` website includes the documentation for several `jj` versions
195+
(`prerelease`, latest release, and the older releases). The top-level
196+
URL <https://martinvonz.github.io/jj> is hardcoded to redirect to
197+
<https://martinvonz.github.io/jj/latest>, which in turn redirects to
198+
the docs for the last stable version.
199+
200+
The different versions of documentation are managed and deployed with
201+
[`mike`](https://github.com/jimporter/mike), which can be run with
202+
`poetry run -- mike`.
203+
204+
On a POSIX system, one way to build the entire website is as follows (on
205+
Windows, you will have to understand the shell script and run the corresponding
206+
commands):
207+
208+
1. Check out `jj` as a Git repository or a co-located `jj + git` repository
209+
(`jj clone --colocate`), cloned from your fork of `jj` (e.g. `jjfan.github.com/jj`).
210+
211+
2. Make sure `jjfan.github.com/jj` includes the `gh-pages` branch of the jj repo
212+
and run `git fetch origin gh-pages`.
213+
214+
3. Go to the Github repository settings, enable Github Pages, and configure them
215+
to use the `gh-pages` branch (this is usually the default).
216+
217+
4. Run the same `sh` script that is used in Github CI (details below):
218+
219+
```shell
220+
.github/scripts/docs-build-deploy 'https://jjfan.github.io/jj/'\
221+
prerelease main --push
222+
```
223+
224+
This should build the version of the docs from the current commit,
225+
deploy it as a new commit to the `gh-pages` branch,
226+
and push the `gh-pages` branch to the origin.
227+
228+
5. Now, you should be able to see the full website, including your latest changes
229+
to the `prerelease` version, at `https://jjfan.github.io/jj/prerelease/`.
230+
231+
6. (Optional) When you are done, you may want to reset the `gh-branches` to the same
232+
spot as it is in the upstream. If you configured the `upstream` remote and are in a
233+
colocated repo, this can be done with:
234+
235+
```shell
236+
jj git fetch --remote upstream
237+
jj branch set gh-pages -r gh-pages@upstream
238+
jj git push --branch upstream
239+
```
240+
241+
#### Explanation of the `docs-build-deploy` script
242+
243+
The script sets up the `site_url` mkdocs config to
244+
`'https://jjfan.github.io/jj/'`. If this config does not match the URL
245+
where you loaded the website, some minor website features (like the
246+
version switching widget) will have reduced functionality.
247+
248+
Then, the script passes the rest of its arguments to `potery run -- mike deploy`, which does
249+
the rest of the job. Run `poetry run -- mike help` to find out what the arguments do.
250+
187251
## Modifying protobuffers (this is not common)
188252

189253
Occasionally, you may need to change the `.proto` files that define jj's data

0 commit comments

Comments
 (0)