Skip to content

Commit 2873fd3

Browse files
pipernlee-butcherlfrancke
authored
Gitpod config (#88)
* Store https://gitlab.com/antora/demo/docs-site/blob/watch-mode/gulpfile.js * Configuration for gitpod workspaces and automatic running antora on changes * Local and Gitpod Antora playbooks Also changes related to the renaming of the Gitpod playbook. * Update the alternative playbook filenames As per the recommendation here: https://docs.antora.org/antora/2.3/playbook/set-up-playbook/ The alternative name is given as a prefix not a postfix. Co-authored-by: lee-butcher <[email protected]> Co-authored-by: Lee Butcher <[email protected]> Co-authored-by: Lars Francke <[email protected]>
1 parent 0628b6e commit 2873fd3

File tree

8 files changed

+4706
-2
lines changed

8 files changed

+4706
-2
lines changed

‎.gitignore

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
build/
2-
.idea/
2+
.idea/
3+
node_modules/

‎.gitpod.Dockerfile

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
FROM gitpod/workspace-full:latest
2+
3+
USER gitpod
4+
5+
RUN npm i -g @antora/cli
6+
RUN npm i -g gulp
7+

‎.gitpod.yml

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
image:
2+
file: .gitpod.Dockerfile
3+
4+
vscode:
5+
extensions:
6+
- hediet.vscode-drawio
7+
- asciidoctor.asciidoctor-vscode
8+
- mechatroner.rainbow-csv
9+
10+
ports:
11+
- port: 5000
12+
onOpen: open-preview
13+
# https://github.com/swapagarwal/swag-for-dev/pull/573
14+
# live-reload: Broken because of bad automatic configuration of live-reload plugin
15+
# See: https://github.com/schickling/gulp-webserver/pull/126
16+
# Once it's released, we will be able to set livereload config with custom `src` target
17+
# to the right URL (found with `gp url <port>`)
18+
- port: 35729
19+
onOpen: ignore
20+
21+
tasks:
22+
- init: >
23+
npm install @antora/site-generator-default gulp-cli gulp gulp-connect
24+
command: >
25+
LIVERELOAD=true gulp

‎README.adoc

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@ NOTE: Antora caches all resources it downloads in the user's cache directory (e.
1616

1717
== Development
1818

19-
During development, it can be helpful to change the playbook so that the source does point at the local directory instead of the remote git repository:
19+
=== Generating the documentation
20+
21+
During development, it can be helpful to use a playbook `local-antora-playbook.yml` which uses content from the local directory instead of the remote git repository.
2022

2123
[source,yaml]
2224
----
@@ -29,3 +31,10 @@ content:
2931
NOTE: Antora does not recognize git submodules as git repositories
3032

3133
The design & layout comes from our https://github.com/stackabletech/documentation-ui[UI repository].
34+
35+
`LIVERELOAD=true gulp` may be used to recreate the built documentation after each edit. The 'live reload' feature does not work over gitpod currently due to https://github.com/schickling/gulp-webserver/pull/126
36+
37+
=== Remote IDE
38+
39+
A remote vscode instance can be used via https://gitpod.io/#/github.com/stackabletech/documentation
40+

‎gitpod-antora-playbook.yml

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
site:
2+
title: Stackable Documentation
3+
url: https://docs.stackable.tech
4+
start_page: home::index.adoc
5+
robots: allow
6+
7+
content:
8+
sources:
9+
- url: https://github.com/stackabletech/agent.git
10+
branches: main
11+
start_path: docs
12+
- url: /workspace/documentation
13+
branches: HEAD
14+
- url: https://github.com/stackabletech/kafka-operator.git
15+
branches: main
16+
start_path: docs
17+
- url: https://github.com/stackabletech/monitoring-operator.git
18+
branches: main
19+
start_path: docs
20+
- url: https://github.com/stackabletech/nifi-operator.git
21+
branches: main
22+
start_path: docs
23+
- url: https://github.com/stackabletech/opa-operator.git
24+
branches: main
25+
start_path: docs
26+
- url: https://github.com/stackabletech/regorule-operator.git
27+
branches: main
28+
start_path: docs
29+
- url: https://github.com/stackabletech/spark-operator.git
30+
branches: main
31+
start_path: docs
32+
- url: https://github.com/stackabletech/zookeeper-operator.git
33+
branches: main
34+
start_path: docs
35+
36+
ui:
37+
bundle:
38+
url: https://repo.stackable.tech/repository/misc/ui-bundle.zip
39+
snapshot: true
40+
supplemental_files:
41+
- path: ui.yml
42+
contents: |
43+
static_files: [ .nojekyll ]
44+
- path: .nojekyll
45+
46+
asciidoc:
47+
attributes:
48+
base-repo: https://github.com/stackabletech

‎gulpfile.js

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// from https://gitlab.com/antora/demo/docs-site/blob/watch-mode/gulpfile.js via https://gitlab.com/antora/antora/-/issues/329
2+
'use strict'
3+
4+
const connect = require('gulp-connect')
5+
const fs = require('fs')
6+
const generator = require('@antora/site-generator-default')
7+
const { reload: livereload } = process.env.LIVERELOAD === 'true' ? require('gulp-connect') : {}
8+
const { series, src, watch } = require('gulp')
9+
const yaml = require('js-yaml')
10+
11+
const playbookFilename = 'gitpod-antora-playbook.yml'
12+
const playbook = yaml.safeLoad(fs.readFileSync(playbookFilename, 'utf8'))
13+
const outputDir = (playbook.output || {}).dir || './build/site'
14+
const serverConfig = { name: 'Preview Site', livereload, port: 5000, root: outputDir }
15+
const antoraArgs = ['--playbook', playbookFilename]
16+
const watchPatterns = playbook.content.sources.filter((source) => !source.url.includes(':')).reduce((accum, source) => {
17+
accum.push(`${source.url}/${source.start_path ? source.start_path + '/' : ''}antora.yml`)
18+
accum.push(`${source.url}/${source.start_path ? source.start_path + '/' : ''}modules/**/*.adoc`)
19+
return accum
20+
}, [])
21+
22+
function generate (done) {
23+
generator(antoraArgs, process.env)
24+
.then(() => done())
25+
.catch((err) => {
26+
console.log(err)
27+
done()
28+
})
29+
}
30+
31+
function serve (done) {
32+
connect.server(serverConfig, function () {
33+
this.server.on('close', done)
34+
watch(watchPatterns, generate)
35+
if (livereload) watch(this.root).on('change', (filepath) => src(filepath, { read: false }).pipe(livereload()))
36+
})
37+
}
38+
39+
module.exports = { serve, generate, default: series(generate, serve) }

‎local-antora-playbook.yml

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
site:
2+
title: Stackable Documentation
3+
url: https://docs.stackable.tech
4+
start_page: home::index.adoc
5+
robots: allow
6+
7+
content:
8+
sources:
9+
- url: https://github.com/stackabletech/agent.git
10+
branches: main
11+
start_path: docs
12+
- url: ./
13+
branches: HEAD
14+
- url: https://github.com/stackabletech/kafka-operator.git
15+
branches: main
16+
start_path: docs
17+
- url: https://github.com/stackabletech/monitoring-operator.git
18+
branches: main
19+
start_path: docs
20+
- url: https://github.com/stackabletech/nifi-operator.git
21+
branches: main
22+
start_path: docs
23+
- url: https://github.com/stackabletech/opa-operator.git
24+
branches: main
25+
start_path: docs
26+
- url: https://github.com/stackabletech/regorule-operator.git
27+
branches: main
28+
start_path: docs
29+
- url: https://github.com/stackabletech/spark-operator.git
30+
branches: main
31+
start_path: docs
32+
- url: https://github.com/stackabletech/zookeeper-operator.git
33+
branches: main
34+
start_path: docs
35+
36+
ui:
37+
bundle:
38+
url: https://repo.stackable.tech/repository/misc/ui-bundle.zip
39+
snapshot: true
40+
supplemental_files:
41+
- path: ui.yml
42+
contents: |
43+
static_files: [ .nojekyll ]
44+
- path: .nojekyll
45+
46+
asciidoc:
47+
attributes:
48+
base-repo: https://github.com/stackabletech

0 commit comments

Comments
 (0)