Initial commit

.github/CONTRIBUTING.adoc

@@ -0,0 +1,70 @@
+= Contributing to Hazelcast Tutorials
+
+This guide covers how to use this template to contribute to Hazelcast tutorials.
+
+== Repository Structure
+
+All tutorials follow the same structure:
+
+- `.github/workflows/build-site.yml`: A build hook that builds the documentation site when a change is merged.
+- `docs/`: Source content in the link:https://docs.antora.org/antora/latest/standard-directories/[standard Antora file and directory structure].
+- `create.sh`: A script that converts the Asciidoc files in the `docs/` directory to a PDF. This script requires the link:https://docs.asciidoctor.org/asciidoctor/latest/cli/[Asciidoctor CLI] to be installed.
+- `antora-playbook-local.yml`: An Antora playbook that builds the tutorials subsite locally.
+- `lib/`: Asciidoc extensions that are needed to generate the tutorials subsite locally.
+- `package.json`: Scripts for building the tutorials subsite locally as well as checking links and serving the files.
+
+== Adding a New Tutorial
+
+. Create a new repository, using this link:https://github.com/hazelcast-guides/base-guide[template].
++
+TIP: Use a brief name for the new repository as it will be the endpoint of the tutorial when it's published.
+
+. Rename the file in `docs/modules/ROOT/pages` to the name of your repository.
+
+. Add the filename to the template in the README.
+
+. Write your tutorial by following the instructions in the file.
+
+. Submit a pull request against the `develop` branch of the link:https://github.com/hazelcast/hazelcast-docs[`hazelcast-docs` repository] to append your tutorial repository to the `content.sources` field in the `antora-playbook.yml` and `antora-playbook-local.yml` files.
++
+For example:
++
+```yaml
+content:
+  sources:
+    - url: https://github.com/hazelcast-guides/<your-repo>
+    branches: main
+    start_path: docs
+```
++
+After the pull request is merged, your tutorial will be available on the documentation site in ~10 minutes.
+
+== Previewing a Tutorial
+
+To preview your content in a local version of the tutorials subsite, do the following:
+
+. Install the required dependencies by running `npm i` at the root of your repository.
+
+. Build the site.
++
+```bash
+npm run-script build-local
+```
++
+You should see the following:
++
+`Site generation complete!`
+
+. Serve the site locally.
++
+```bash
+npm run-script serve
+```
++
+This script automatically copies the local URL to your clipboard.
+
+. In a web browser, paste the URL into the address bar.
+
+You can browse the site for your tutorial, or you can append the name of your tutorial's filename to the end of the URL. For example: http://localhost:3000/tutorials/<your tutorial>.
+
+NOTE: Search does not work locally. The search bar displays results only for tutorials that are already published on docs.hazelcast.com.

.github/workflows/build-site.yml

@@ -0,0 +1,13 @@
+# This workflow takes the contents of the branches/tags and builds the production documentation site
+name: Build production site
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Trigger build
+      run: curl -X POST -d {} https://api.netlify.com/build_hooks/6238ac2881e6d20c7db8e6c8

.gitignore

@@ -0,0 +1,15 @@
+target/
+.idea/
+.settings/
+.classpath
+.directory
+.project
+.surefire-*
+.DS_Store
+*.iml
+*.ipr
+*.iws
+*.txt
+node_modules/
+local-docs/
+package-lock.json

README.adoc

@@ -0,0 +1,3 @@
+// Replace <filename> with the name of your repository, and replace <tutorial name> with the title of the tutorial.
+// For guidance on using this template, see .github/CONTRIBUTING.adoc
+This repository hosts the documentation and code samples for the link:https://docs.hazelcast.com/tutorials/<filename>[<tutorial name> tutorial].

antora-playbook-local.yml

@@ -0,0 +1,31 @@
+site:
+  title: Documentation
+  start_page: tutorials::index.adoc
+  url: http:localhost:3000
+  keys:
+    docsearch_id: 'QK2EAH8GB0'
+    docsearch_api: 'ef7bd9485eafbd75d6e8425949eda1f5'
+    docsearch_index: 'prod_hazelcast_docs'
+content:
+  sources: 
+  - url: https://github.com/hazelcast/hazelcast-docs
+    branches: main
+    start_paths: [tutorials, home]
+  - url: https://github.com/hazelcast-guides/adoc-templates.git
+    branches: antora-doc
+  - url: .
+    branches: master
+    start_paths: docs
+ui: 
+  bundle:
+    url: https://github.com/hazelcast/hazelcast-docs-ui/releases/latest/download/ui-bundle.zip
+    snapshot: true
+asciidoc:
+  attributes:
+    page-pagination: true@
+    # Allows us to use UI macros. See https://docs.asciidoctor.org/asciidoc/latest/macros/ui-macros/
+    page-experimental: true
+    idprefix: ''
+    idseparator: '-'
+  extensions:
+    - ./lib/tabs-block.js

create.sh

@@ -0,0 +1,2 @@
+asciidoctor -D . -a allow-uri-read docs/modules/ROOT/pages/*.adoc;
+asciidoctor-pdf -D . -a allow-uri-read docs/modules/ROOT/pages/*.adoc;

docs/antora.yml

@@ -0,0 +1,3 @@
+name: tutorials
+version: ~
+

docs/modules/ROOT/pages/rename-me.adoc

@@ -0,0 +1,57 @@
+////
+Make sure to rename this file to the name of your repository and add the filename to the README. This filename must not conflict with any existing tutorials.
+////
+
+// Describe the title of your article by replacing 'Tutorial template' with the page name you want to publish.
+= Tutorial template
+// Add required variables
+:page-layout: tutorial
+:page-product: // Required: Define the product filter for this tutorial. Add one of the following: platform, imdg, cloud, operator
+:page-categories: // Optional: Define the categories for this tutorial. Check the current categories on the tutorials homepage (https://docs.hazelcast.com/tutorials/). Add one or more of the existing categories or add new ones as a comma-separated list. Make sure that you use title case for all categories. 
+:page-lang: java // Optional: Define what Hazelcast client languages are supported by this tutorial. Leave blank or add one or more of: java, go, python, cplus, node, csharp.
+:page-enterprise: // Required: Define whether this tutorial requires an Enterprise license (true or blank)
+:page-est-time: // Required: Define the estimated number of time required to complete the tutorial in minutes. For example, 10 mins
+:description: // Required: Summarize what this tutorial is about in a sentence or two. What you put here is reused as the tutorial's first paragraph and included in HTML description tags. Start the sentence with an action verb such as 'Deploy' or 'Connect'.
+
+{description}
+
+// Give some context about the use case for this tutorial. What will the reader learn?
+== Context
+
+// Optional: What does the reader need before starting this tutorial? Think about tools or knowledge. Delete this section if your readers can dive straight into the lesson without requiring any prerequisite knowledge.
+== Before you Begin
+
+Before starting this tutorial, make sure that you meet the following prerequisites:
+
+* Prerequisite one
+* Prerequisite two
+* etc
+
+== Step 1. <Step Title>
+
+////
+Introduce what your audience will learn in each step, then continue to write the steps in the tutorial.
+You can choose one of these approaches to write your tutorial part:
+
+* In a narrative style if your parts are short or you are using screenshots to do most of the talking.   
+* In a "Goal > Steps > Outcome" structure to build a predictable flow in all your tutorial parts.
+
+Whatever option you choose when designing your tutorial should be carried through in subsequent parts.
+////
+
+== Step 2. <Step Title>
+
+////
+Continue the design approach you chose in the previous part and continue it through to the end of the tutorial.
+////
+
+== Summary
+
+////
+Summarise what knowledge the reader has gained by completing the tutorial, including a summary of each step's goals (this is a good way to validate whether your tutorial has covered all you need it to.)
+////
+
+
+== See Also
+
+// Optionally, add some links to resources, such as other related guides.

lib/tabs-block.js

@@ -0,0 +1,80 @@
+/* Copyright (c) 2018 OpenDevise, Inc.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+/**
+ * Extends the AsciiDoc syntax to support a tabset. The tabset is created from
+ * a dlist enclosed in an example block that is marked with the tabs style.
+ *
+ * Usage:
+ *
+ *  [tabs]
+ *  ====
+ *  Tab A::
+ *  +
+ *  --
+ *  Contents of tab A.
+ *  --
+ *  Tab B::
+ *  +
+ *  --
+ *  Contents of tab B.
+ *  --
+ *  ====
+ *
+ * @author Dan Allen <[email protected]>
+ */
+const IdSeparatorCh = '-'
+const ExtraIdSeparatorsRx = /^-+|-+$|-(-)+/g
+const InvalidIdCharsRx = /[^a-zA-Z0-9_]/g
+const List = Opal.const_get_local(Opal.module(null, 'Asciidoctor'), 'List')
+const ListItem = Opal.const_get_local(Opal.module(null, 'Asciidoctor'), 'ListItem')
+
+const generateId = (str, idx) =>
+  `tabset${idx}_${str.toLowerCase().replace(InvalidIdCharsRx, IdSeparatorCh).replace(ExtraIdSeparatorsRx, '$1')}`
+
+function tabsBlock () {
+  this.onContext('example')
+  this.process((parent, reader, attrs) => {
+    const createHtmlFragment = (html) => this.createBlock(parent, 'pass', html)
+    const tabsetIdx = parent.getDocument().counter('idx-tabset')
+    const nodes = []
+    nodes.push(createHtmlFragment('<div class="tabset is-loading">'))
+    const container = this.parseContent(this.createBlock(parent, 'open'), reader)
+    const sourceTabs = container.getBlocks()[0]
+    if (!(sourceTabs && sourceTabs.getContext() === 'dlist' && sourceTabs.getItems().length)) return
+    const tabs = List.$new(parent, 'ulist')
+    tabs.addRole('tabs')
+    const panes = {}
+    sourceTabs.getItems().forEach(([[title], details]) => {
+      const tab = ListItem.$new(tabs)
+      tabs.$append(tab)
+      const id = generateId(title.getText(), tabsetIdx)
+      tab.text = `[[${id}]]${title.text}`
+      let blocks = details.getBlocks()
+      const numBlocks = blocks.length
+      if (numBlocks) {
+        if (blocks[0].context === 'open' && numBlocks === 1) blocks = blocks[0].getBlocks()
+        panes[id] = blocks.map((block) => (block.parent = parent) && block)
+      }
+    })
+    nodes.push(tabs)
+    nodes.push(createHtmlFragment('<div class="content">'))
+    Object.entries(panes).forEach(([id, blocks]) => {
+      nodes.push(createHtmlFragment(`<div class="tab-pane" aria-labelledby="${id}">`))
+      nodes.push(...blocks)
+      nodes.push(createHtmlFragment('</div>'))
+    })
+    nodes.push(createHtmlFragment('</div>'))
+    nodes.push(createHtmlFragment('</div>'))
+    parent.blocks.push(...nodes)
+  })
+}
+
+function register (registry) {
+  registry.block('tabs', tabsBlock)
+}
+
+module.exports.register = register

package.json

@@ -0,0 +1,22 @@
+{
+  "name": "hazelcast-docs-playbook",
+  "version": "1.0.0",
+  "description": "Script for working with Hazelcast tutorials locally",
+  "author": "Jake Cahill",
+  "license": "ISC",
+  "scripts": {
+    "build-local": "antora --to-dir local-docs --fetch --generator @antora/site-generator-default antora-playbook-local.yml",
+    "check-links-local": "antora --generator @antora/xref-validator antora-playbook-local.yml",
+    "serve": "serve local-docs",
+    "expose": "ngrok http 5000"
+  },
+  "devDependencies": {
+    "@antora/cli": "^3.0.0",
+    "@antora/site-generator-default": "^3.0.0",
+    "@antora/xref-validator": "gitlab:antora/xref-validator",
+    "@djencks/antora-aggregate-collector": "^0.1.0-beta.1",
+    "asciidoctor-kroki": "^0.10.0",
+    "ngrok": "^4.2.2",
+    "serve": "^13.0.2"
+  }
+}