Skip to content

Commit d788cbe

Browse files
JakeSCahillJakeSCahill
committed
Set up repository
1 parent 6ede8cf commit d788cbe

17 files changed

+1162
-2
lines changed

‎.gitignore

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
/node_modules/
2+
/test/
3+
/build/
4+
.DS_Store
5+
package-lock.json

‎README.adoc

+173
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
= Documentation for Hazelcast Platform Operator
2+
// Settings:
3+
ifdef::env-github[]
4+
:warning-caption: :warning:
5+
endif::[]
6+
// URLs:
7+
:url-org: https://github.com/hazelcast
8+
:url-contribute: https://github.com/hazelcast/hazelcast-docs/blob/develop/.github/CONTRIBUTING.adoc
9+
:url-ui: {url-org}/hazelcast-docs-ui
10+
:url-playbook: {url-org}/hazelcast-docs
11+
:url-staging: https://hardcore-allen-f5257d.netlify.app/
12+
:url-cc: https://creativecommons.org/licenses/by-nc-sa/3.0/
13+
:url-operator-docs: {url-org}/hazelcast-platform-operator-docs
14+
:url-mc-docs: {url-org}/management-center-docs
15+
16+
image:https://img.shields.io/badge/Build-Staging-yellow[link="{url-staging}"]
17+
18+
This repository contains the Antora components for the Hazelcast Platform Operator documentation.
19+
20+
The documentation source files are marked up with AsciiDoc.
21+
22+
== Docs Structure
23+
24+
This section describes some important information about how this repository is structured:
25+
26+
- The component name, version, and start page are configured in each branch's `antora.yml` file.
27+
- The navigation for all modules is stored in the ROOT module's `nav.adoc` file.
28+
- The {url-playbook}[docs site playbook] instructs Antora to automatically build the site using content in the `main` branch as well as any branches that are prefixed with `v/`.
29+
30+
== Release Workflow
31+
32+
Documentation for new releases is hosted in versioned branches that are prefixed with `v/`. The `latest-dev` content (snapshot content) is stored in the `main` branch.
33+
34+
We support documentation for the latest patch releases of minor versions. For example, content for the `5.0` version is hosted in the `v/5.0` branch. This branch contains content for the latest patch release of version 5.0.
35+
36+
NOTE: The documentation build process is triggered whenever you create a new branch with the `v/` prefix, push to an existing `v/` branch, or push to the `main` branch.
37+
38+
=== Snapshot Releases
39+
40+
Add the new snapshot version to the following:
41+
42+
[cols="1m,1m,1m,1m"]
43+
|===
44+
|Repository|Branch|File|Fields
45+
46+
|{url-operator-docs}[hazelcast-platform-operator-docs]
47+
|main
48+
|docs/antora.yml
49+
a|
50+
- `version`
51+
- `display_version`
52+
- `full-version`
53+
54+
|{url-playbook}[hazelcast-docs]
55+
a|`main` and `develop`
56+
|_redirects
57+
|/hazelcast-operator/latest-dev/*
58+
59+
|
60+
|
61+
|search-config.json
62+
a|Update the snapshot version in these fields:
63+
64+
- `start_urls.tags`
65+
- `start_urls.variables.version`
66+
67+
|===
68+
69+
=== Latest Releases
70+
71+
Add the `major.minor` version to the following:
72+
73+
[cols="1m,1m,1m,1m"]
74+
|===
75+
|Repository|Branch|File|Fields
76+
77+
|{url-operator-docs}[hazelcast-platform-operator-docs]
78+
|v/{major.minor version}
79+
|docs/antora.yml
80+
a|
81+
- `version`
82+
- `display_version`
83+
84+
|{url-playbook}[hazelcast-docs]
85+
a|`main` and `develop`
86+
|_redirects
87+
|/hazelcast-operator/latest/*
88+
89+
|
90+
|
91+
|search-config.json
92+
a| Create a new object in the `start_urls` array.
93+
94+
``
95+
{
96+
"url": "https://docs.hazelcast.com/hazelcast-operator/(?P<version>.*?)/",
97+
"tags": [
98+
"hazelcast-operator-{major.minor version}"
99+
],
100+
"variables": {
101+
"version": ["{major.minor version}"]
102+
},
103+
"selectors_key": "operator"
104+
}
105+
``
106+
107+
|===
108+
109+
Add the full version `major.minor.patch` to the following:
110+
111+
[cols="1m,1m,1m"]
112+
|===
113+
|Repository|File|Fields
114+
115+
|{url-operator-docs}[hazelcast-platform-operator-docs]
116+
|docs/antora.yml
117+
a|
118+
- `full-version`
119+
|===
120+
121+
=== Patch Releases
122+
123+
In the `v/` branch for the minor version whose patch you are releasing, update the `asciidoc.attributes.full-version` field in the `antora.yml` file to the new patch version. For example, if you are releasing version 5.0.3, find the `v/5.0` branch and update the `asciidoc.attributes.full-version` field in the `antora.yml` file with 5.0.3.
124+
125+
NOTE: As soon as you push content to this branch, GitHub will trigger a new build of the site, which will include your new content.
126+
127+
=== Creating Release Branches
128+
129+
. If you are releasing a new major version, create a release branch from the `main` branch.
130+
+
131+
For example, if you are releasing version 5.1, create a new release branch named `5.1` from the `main` branch.
132+
133+
. Update the fields mentioned in <<latest-releases, Latest Releases>>.
134+
135+
. Remove the `prerelease: true` field from the `docs/antora.yml` file of the `hz-docs` repository.
136+
+
137+
IMPORTANT: If you are creating a branch for a beta release, do not remove this field.
138+
139+
. When you are ready to release, create a maintentance branch from the release branch.
140+
+
141+
NOTE: As soon as you push the maintenance branch to the repository, GitHub will trigger a new build of the site, which will include your new content.
142+
143+
. Make sure to delete the release branch.
144+
+
145+
For example, if you released version `5.1`, delete the `5.1` branch. This step helps to keep the repository clean of release branches.
146+
147+
== GitHub Actions
148+
149+
To automate some elements of the build process, this repository includes the following GitHub Actions:
150+
151+
.GitHub Actions
152+
[cols="m,a,a"]
153+
|===
154+
|File |Description |Triggers
155+
156+
|validate-site.yml
157+
|Validates that all internal and external links are working
158+
|On a pull request to the `main` branch and `v/` maintenance branches
159+
160+
|build-site.yml
161+
|Builds the production documentation site by sending a build hook to Netlify (the hosting platform that we use)
162+
|On a push to the `main` branch and any `v/` maintenance branches
163+
|===
164+
165+
== Contributing
166+
167+
If you want to add a change or contribute new content, see our {url-contribute}[contributing guide].
168+
169+
To let us know about something that you'd like us to change, consider {url-org}/hazelcast-operator/issues/new[creating an issue].
170+
171+
== License
172+
173+
All documentation is available under the terms of a link:{url-cc}[Creative Commons License]

‎README.md

-2
This file was deleted.

‎antora-playbook-local.yml

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
site:
2+
title: Documentation
3+
url: http:localhost:5000
4+
start_page: hazelcast-operator:ROOT:get-started.adoc
5+
robots: disallow
6+
keys:
7+
docsearch_id: 'QK2EAH8GB0'
8+
docsearch_api: 'ef7bd9485eafbd75d6e8425949eda1f5'
9+
docsearch_index: 'prod_hazelcast_docs'
10+
content:
11+
sources:
12+
- url: .
13+
branches: HEAD
14+
start_path: docs
15+
ui:
16+
bundle:
17+
url: https://github.com/hazelcast/hazelcast-docs-ui/releases/download/v2.4/ui-bundle.zip #../hazelcast-docs-ui/build/ui-bundle.zip
18+
snapshot: true
19+
asciidoc:
20+
attributes:
21+
# Download images from kroki at build time (does not work for inline images)
22+
kroki-fetch-diagram: true
23+
# Inlude next and previous links on each page
24+
page-pagination: true@
25+
idprefix: ''
26+
# Separate anchor link names by dashes
27+
idseparator: '-'
28+
# Docs survey that's linked on pages
29+
page-survey: https://www.surveymonkey.co.uk/r/NYGJNF9
30+
extensions:
31+
- ./docs-tabs-library/tabs-block.js
32+
- asciidoctor-kroki

‎antora-playbook.yml

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
site:
2+
title: Documentation
3+
url: https://hardcore-allen-f5257d.netlify.app/
4+
start_page: hazelcast-operator:get-started.adoc
5+
robots: disallow
6+
keys:
7+
docsearch_id: 'QK2EAH8GB0'
8+
docsearch_api: 'ef7bd9485eafbd75d6e8425949eda1f5'
9+
docsearch_index: 'prod_hazelcast_docs'
10+
content:
11+
sources:
12+
- url: .
13+
branches: HEAD
14+
start_path: docs
15+
ui:
16+
bundle:
17+
url: https://github.com/hazelcast/hazelcast-docs-ui/releases/download/v2.4/ui-bundle.zip #../hazelcast-docs-ui/build/ui-bundle.zip
18+
snapshot: true
19+
asciidoc:
20+
attributes:
21+
# Download images from kroki at build time (does not work for inline images)
22+
kroki-fetch-diagram: true
23+
# Inlude next and previous links on each page
24+
page-pagination: true
25+
idprefix: ''
26+
# Separate anchor link names by dashes
27+
idseparator: '-'
28+
# Docs survey that's linked on pages
29+
page-survey: https://www.surveymonkey.co.uk/r/NYGJNF9
30+
extensions:
31+
- ./docs-tabs-library/tabs-block.js
32+
- asciidoctor-kroki

‎check-links-playbook.yml

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
site:
2+
title: Documentation
3+
url: http:localhost:5000
4+
content:
5+
sources:
6+
- url: .
7+
branches: HEAD
8+
start_path: docs
9+
- url: https://github.com/hazelcast/imdg-docs
10+
branches: [v/*]
11+
start_path: docs
12+
- url: https://github.com/hazelcast/hz-docs
13+
branches: [main]
14+
start_path: docs
15+
- url: https://github.com/hazelcast/management-center-docs
16+
branches: [main]
17+
start_path: docs
18+
- url: https://github.com/hazelcast/cloud-docs
19+
branches: [main]
20+
start_path: docs
21+
ui:
22+
bundle:
23+
url: https://github.com/hazelcast/hazelcast-docs-ui/releases/download/v2.4/ui-bundle.zip #../hazelcast-docs-ui/build/ui-bundle.zip
24+
snapshot: true
25+
asciidoc:
26+
attributes:
27+
# Download images from kroki at build time (does not work for inline images)
28+
kroki-fetch-diagram: true
29+
# Inlude next and previous links on each page
30+
page-pagination: true
31+
idprefix: ''
32+
# Separate anchor link names by dashes
33+
idseparator: '-'
34+
page-survey: https://www.surveymonkey.co.uk/r/NYGJNF9
35+
extensions:
36+
- ./docs-tabs-library/tabs-block.js
37+
- asciidoctor-kroki

‎docs-tabs-library/tabs-block.js

+80
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
/* Copyright (c) 2018 OpenDevise, Inc.
2+
*
3+
* This Source Code Form is subject to the terms of the Mozilla Public
4+
* License, v. 2.0. If a copy of the MPL was not distributed with this
5+
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6+
7+
/**
8+
* Extends the AsciiDoc syntax to support a tabset. The tabset is created from
9+
* a dlist enclosed in an example block that is marked with the tabs style.
10+
*
11+
* Usage:
12+
*
13+
* [tabs]
14+
* ====
15+
* Tab A::
16+
* +
17+
* --
18+
* Contents of tab A.
19+
* --
20+
* Tab B::
21+
* +
22+
* --
23+
* Contents of tab B.
24+
* --
25+
* ====
26+
*
27+
* @author Dan Allen <dan@opendevise.com>
28+
*/
29+
const IdSeparatorCh = '-'
30+
const ExtraIdSeparatorsRx = /^-+|-+$|-(-)+/g
31+
const InvalidIdCharsRx = /[^a-zA-Z0-9_]/g
32+
const List = Opal.const_get_local(Opal.module(null, 'Asciidoctor'), 'List')
33+
const ListItem = Opal.const_get_local(Opal.module(null, 'Asciidoctor'), 'ListItem')
34+
35+
const generateId = (str, idx) =>
36+
`tabset${idx}_${str.toLowerCase().replace(InvalidIdCharsRx, IdSeparatorCh).replace(ExtraIdSeparatorsRx, '$1')}`
37+
38+
function tabsBlock () {
39+
this.onContext('example')
40+
this.process((parent, reader, attrs) => {
41+
const createHtmlFragment = (html) => this.createBlock(parent, 'pass', html)
42+
const tabsetIdx = parent.getDocument().counter('idx-tabset')
43+
const nodes = []
44+
nodes.push(createHtmlFragment('<div class="tabset is-loading">'))
45+
const container = this.parseContent(this.createBlock(parent, 'open'), reader)
46+
const sourceTabs = container.getBlocks()[0]
47+
if (!(sourceTabs && sourceTabs.getContext() === 'dlist' && sourceTabs.getItems().length)) return
48+
const tabs = List.$new(parent, 'ulist')
49+
tabs.addRole('tabs')
50+
const panes = {}
51+
sourceTabs.getItems().forEach(([[title], details]) => {
52+
const tab = ListItem.$new(tabs)
53+
tabs.$append(tab)
54+
const id = generateId(title.getText(), tabsetIdx)
55+
tab.text = `[[${id}]]${title.text}`
56+
let blocks = details.getBlocks()
57+
const numBlocks = blocks.length
58+
if (numBlocks) {
59+
if (blocks[0].context === 'open' && numBlocks === 1) blocks = blocks[0].getBlocks()
60+
panes[id] = blocks.map((block) => (block.parent = parent) && block)
61+
}
62+
})
63+
nodes.push(tabs)
64+
nodes.push(createHtmlFragment('<div class="content">'))
65+
Object.entries(panes).forEach(([id, blocks]) => {
66+
nodes.push(createHtmlFragment(`<div class="tab-pane" aria-labelledby="${id}">`))
67+
nodes.push(...blocks)
68+
nodes.push(createHtmlFragment('</div>'))
69+
})
70+
nodes.push(createHtmlFragment('</div>'))
71+
nodes.push(createHtmlFragment('</div>'))
72+
parent.blocks.push(...nodes)
73+
})
74+
}
75+
76+
function register (registry) {
77+
registry.block('tabs', tabsBlock)
78+
}
79+
80+
module.exports.register = register

‎docs/antora.yml

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
name: hazelcast-operator
2+
title: Hazelcast Operator
3+
# Version in the URL
4+
version: '5-preview-snapshot'
5+
# Version in the version selector (we display only the latest major.minor version)
6+
display_version: '5-preview-snapshot'
7+
# Displays a banner to inform users that this is a prerelease version
8+
prerelease: true
9+
asciidoc:
10+
attributes:
11+
# The full major.minor.patch version, which is used as a variable in the docs for things like download links
12+
full-version: '5-preview-snapshot'
13+
page-latest-supported-mc: '5.0'
14+
page-latest-supported-hazelcast: '5.0'
15+
page-toclevels: 1@
16+
# Used for the Report an issue link
17+
page-ghissue: https://github.com/hazelcast/hazelcast-platform-operator-docs/issues/new
18+
nav:
19+
- modules/ROOT/nav.adoc

0 commit comments

Comments
 (0)