Skip to content

Commit 198f0e3

Browse files
bbatsovbbatsov
committed
Automate the deployment of the site with GHA
1 parent bb14aed commit 198f0e3

File tree

4 files changed

+115
-26
lines changed

4 files changed

+115
-26
lines changed

‎.github/workflows/publish.yml

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Publish to GitHub Pages
2+
on:
3+
push:
4+
branches: [master]
5+
# Allows you to run this workflow manually from the Actions tab
6+
workflow_dispatch:
7+
concurrency:
8+
group: github-pages
9+
cancel-in-progress: false
10+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
11+
permissions:
12+
contents: read
13+
pages: write
14+
id-token: write
15+
jobs:
16+
build:
17+
runs-on: ubuntu-latest
18+
environment:
19+
name: github-pages
20+
url: ${{ steps.deployment.outputs.page_url }}
21+
steps:
22+
- name: Checkout repository
23+
uses: actions/checkout@v4
24+
- name: Configure Pages
25+
uses: actions/configure-pages@v5
26+
- name: Install Node.js
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: "18"
30+
- name: Install Antora
31+
run: npm i antora
32+
- name: Generate Site
33+
run: npx antora antora-playbook.yml
34+
- name: Upload Artifacts
35+
uses: actions/upload-pages-artifact@v3
36+
with:
37+
path: build/site
38+
- name: Deploy to GitHub Pages
39+
id: deployment
40+
uses: actions/deploy-pages@v4

‎Makefile

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,4 @@ npm: package.json
88
build: npm
99
npm run antora -- --fetch antora-playbook.yml
1010

11-
deploy: build
12-
git add docs
13-
git commit -m 'Update site docs'
14-
git push
11+

‎README.adoc

Lines changed: 41 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,14 @@
22

33
The site is generated from the AsciiDoc files in the link:https://github.com/clojure-emacs/cider/tree/master/doc[doc] folder of nREPL's GitHub repo and is published to https://docs.cider.mx.
44
link:https://antora.org[Antora] is used to convert the manual into HTML.
5-
The filesystem layout is described at https://docs.antora.org/antora/2.0/component-structure/
5+
The filesystem layout is described at https://docs.antora.org/antora/3.1/component-structure/
66

77
To make changes to the manual you simply have to change the files under `doc`.
88
The manual will be regenerated manually periodically.
99

10+
NOTE: If you want to make changes to the manual's page structure you'll have to edit
11+
link:https://github.com/clojure-emacs/cider/blob/master/doc/modules/ROOT/nav.adoc[nav.adoc].
12+
1013
== Installing Antora
1114

1215
Installing the Antora is super simple:
@@ -29,16 +32,47 @@ $ cd docs.cider.mx
2932
$ make build
3033
----
3134

32-
After you're done with the initial setup you can use the `deploy` task to push changes to the site:
35+
To check the generated site you can simply open `build/site/index.html` in your favourite browser.
36+
37+
== Deploying the Site
38+
39+
NOTE: You'll need commit access to the repository for this to work.
40+
41+
The site is automatically deployed to GitHub pages using a GitHub Action.
42+
The action will be triggered by any push to the `master` branch.
43+
It can also be triggered manually if needed.
44+
45+
== Using Docker
46+
47+
If you prefer not to install Antora on your local machine, you can build the documentation
48+
inside a Docker container like this:
3349

3450
[source]
3551
----
36-
$ make deploy
52+
$ docker run --rm -t -v $(pwd):/build/site antora/antora:3.1.10 --fetch /docs/antora-playbook.yml
3753
----
3854

39-
NOTE: You'll need commit access to the repository for this to work.
55+
== Updating the Playbook
4056

41-
To check the generated site you can simply open `docs/index.html` in your favourite browser.
57+
When cutting new releases you'll have to updated `antora-playbook.yml` to mention
58+
their relevant tags from which the documentation needs to be build. Here's how this
59+
looks for one of the projects:
4260

43-
If you want to make changes to the manual's page structure you'll have to edit
44-
link:https://github.com/clojure-emacs/cider/blob/master/doc/modules/ROOT/nav.adoc[nav.adoc].
61+
[source]
62+
----
63+
- url: https://github.com/clojure-emacs/cider.git
64+
branches: master
65+
tags: ['v1.7.0', 'v1.8.0']
66+
start_path: docs
67+
----
68+
69+
TIP: You need to add one such block for each new CIDER module you're adding to the docs site.
70+
71+
After releases of CIDER you also need to update the default landing
72+
version (it should always be the latest version).
73+
74+
== Troubleshooting
75+
76+
The most common mistake that people make is to forget to update the version of an Antora docs module
77+
after cutting a release. This will result in an error saying you've got the same version in two branches (e.g. `master`
78+
and `v1.0`). Fixing this is pretty simple - just update the version to `master` in `antora.yml`.

‎antora-playbook.yml

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -3,25 +3,43 @@ site:
33
url: https://docs.cider.mx
44
start_page: cider::index.adoc
55
keys:
6-
google_analytics: 'UA-140176314-1'
6+
google_analytics: "UA-140176314-1"
77
content:
88
sources:
9-
- url: https://github.com/clojure-emacs/cider.git
10-
branches: master
11-
tags: ['v1.0.0', 'v1.1.1', 'v1.2.0', 'v1.3.0', 'v1.4.0', 'v1.5.0', 'v1.6.0', 'v1.7.0', 'v1.8.0', 'v1.9.0', 'v1.11.0', 'v1.12.0', 'v1.13.0', 'v1.14.0', 'v1.15.0', 'v1.16.0']
12-
start_path: doc
13-
- url: https://github.com/clojure-emacs/cider-nrepl.git
14-
branches: master
15-
tags: ['v0.24.0', 'v0.25.1', 'v0.26.0', 'v0.43.0', 'v0.49.0']
16-
start_path: doc
9+
- url: https://github.com/clojure-emacs/cider.git
10+
branches: master
11+
tags:
12+
[
13+
"v1.0.0",
14+
"v1.1.1",
15+
"v1.2.0",
16+
"v1.3.0",
17+
"v1.4.0",
18+
"v1.5.0",
19+
"v1.6.0",
20+
"v1.7.0",
21+
"v1.8.0",
22+
"v1.9.0",
23+
"v1.11.0",
24+
"v1.12.0",
25+
"v1.13.0",
26+
"v1.14.0",
27+
"v1.15.0",
28+
"v1.16.0",
29+
]
30+
start_path: doc
31+
- url: https://github.com/clojure-emacs/cider-nrepl.git
32+
branches: master
33+
tags: ["v0.24.0", "v0.25.1", "v0.26.0", "v0.43.0", "v0.49.0"]
34+
start_path: doc
1735
asciidoc:
1836
attributes:
19-
experimental: ''
20-
idprefix: ''
21-
idseparator: '-'
22-
linkattrs: ''
37+
experimental: ""
38+
idprefix: ""
39+
idseparator: "-"
40+
linkattrs: ""
2341
toc: ~
24-
page-pagination: ''
42+
page-pagination: ""
2543
urls:
2644
latest_version_segment: latest
2745
latest_version_segment_strategy: redirect:to
@@ -31,4 +49,4 @@ ui:
3149
snapshot: true
3250
supplemental_files: ./supplemental-ui
3351
output:
34-
dir: ./docs
52+
dir: build/site

0 commit comments

Comments
 (0)