hazelcast/hazelcast-docs

Hazelcast documentation playbook

Hazelcast Documentation Site

This repository hosts an Antora playbook project for the Hazelcast documentation site.

Table of Contents

• Introduction to Antora
• The Playbook
• Documentation Content
• Home Component
• Tutorials Component
• Custom Asciidoctor Extensions
• Production and Staging Sites
• Redirects
• Search
• Generating PDFs
• GitHub Actions
• Contributing

Introduction to Antora

Antora is a static site generator that facilitates a docs-as-code workflow.

In Antora, documentation is stored in Git repositories and processed to output a static website.

Documentation can be stored in one or more repositories, using either branches or tags to version it.

Antora uses Asciidoctor.js to convert Asciidoc to HTML, then it uses Handlebars to set that HTML into a page layout.

Note	The page layouts and UI code (css, JavaScript, Handlebars templates) are stored in a separate repository, which outputs a ui-bundle.zip file that this project references in the playbook.

Tip	Learn more about Antora with this excellent introduction on YouTube.

The Playbook

The playbook defines the content sources (repositories and branches), site URL, UI bundle URL, global AsciiDoc attributes, and Asciidoctor extensions.

This project has two playbook files, which configure the build process for the documentation site:

• antora-playbook-local.yml: For local builds

• antora-playbook.yml: For production builds (used by our hosting provider Netlify)

Documentation Content

Source content for the documentation site is marked up in Asciidoc.

The current playbooks pull content from the following repositories:

• Platform documentation

• Cloud documentation

• IMDG documentation

• Platform Operator documentation

• Management Center documentation

Inside these repositories, content may be stored in the following:

• master/main branch: The latest-dev content, which represents the current development version of the product

• archived-versions branch: Legacy content that is not hosted on Antora, but instead given a single page with a link to the legacy documentation site

• Branches prefixed with v/: Versioned releases

Note	To learn about release workflows, see the README of a content repository.

Home Component

The home/ directory in this repository contains the Home documentation component. The source code for the home page is in the body-home.hbs template of the hazelcast-docs-ui repository.

Tutorials Component

The tutorials/ directory in this repository contains the Tutorials documentation component. The source code for the tutorials subsite is in the tutorials-*.hbs templates of the hazelcast-docs-ui repository.

For information about contributing new tutorials, see Tutorial Templates

Custom Asciidoctor Extensions

The custom extension in the lib/ directory processes the Asciidoc tabs blocks to generate tabbed code samples in the output HTML.

For more information about writing Asciidoctor.js extensions, see the Asciidoctor docs.

Production and Staging Sites

The documentation site is hosted on Netlify, which builds two versions of the site from this GitHub repository:

• Production site: This site is hosted on https://docs.hazelcast.com and is built from the main branch

• Staging site: This site is hosted on https://develop—​nifty-wozniak-71a44b.netlify.app/home/ and is built from the develop branch

To preview changes, all pull requests are made to the develop branch. When the team are happy with the changes, the develop branch is merged into the main branch to deploy the changes to the production site.

Redirects

To make it easy for users to find and bookmark the latest content, we use the following aliases:

• latest: The latest stable version.

• latest-dev: The latest development version.

These aliases are configured in the _redirects file, which Netlify uses to redirect to their actual versioned content.

For details about this file, see the Netlify documentation.

Search

The search bar in the documentation is powered by an Algolia search index.

Once a day, we use a DocSearch scraper to index the site, using a GitHub Action, and to send that index to Algolia.

To index the documentation, DocSearch uses our search-config.json file. For more information about search configuration, see the DocSearch documentation.

Generating PDFs

You can generate a PDF of the following documentation:

• Hazelcast Platform version 5.0

• Hazelcast Platform version 5.1

To generate PDFs, you’ll need the following prerequisites:

• At least Ruby 2.7

• Node.js 16, preferably using nvm for the install

• Make sure that the PATH environment variable includes both Ruby and Node

To generate the PDFs, do the following in the root of this repository:

1. Install the dependencies.

   npm i

2. Install Asciidoctor PDF.

   bundle --path=.bundle/gems

   Note	On Windows, you may need to replace the forward slash in the --path value with a backslash (i.e., --path=.bundle\gems).

3. Execute a script to generate the PDFs for a version of the documentation.

   npm run-script generate-pdfs-platform-5-1

This script generates a PDF for the Hazelcast Platform 5.1 documentation.

The result of this script is a pdf-docs directory, in which the artifacts for the PDF files are assembled and the PDF files are generated.

Some errors are displayed in the output, but you can ignore them.

• Management Center links are broken: Since the script builds only a PDF of the Platform documentation, it’s normal that these links are broken.

• null startLine: The script uses the Antora assembler extension, which is in an alpha state. These errors are generated from the PDF converter. The output does not appear to be broken, so you can ignore this type of error.

We will track the status of the extension and update it when new releases are available.

GitHub Actions

To automate some elements of the build process, this repository includes the following GitHub Actions:

Table 1. GitHub Actions

File	Description	Triggers
index-site.yml	Runs the DocSearch scraper in a Docker container to index the site and send the index to Algolia	1st and 15th of every month at 00:00 UTC Note We used to run this once per day, but it was causing overage charges. The crawler that we use uploads a temporary index before deleting the old one. This causes us to go over our limit more than three days in a month, which is the grace period that Algolia provides.
publish-to-production.yml	Merges the develop branch into the main branch to publish changes on the staging site to production.	Manual

As well as these actions, content repositories that are listed under the content.sources field in the antora-playbook.yml file also include GitHub actions to trigger builds of the production site.

content:
  sources:
  - url: https://github.com/hazelcast/imdg-docs
    branches: [master]
    start_path: docs

Whenever content in the repository’s listed branches are changed, the GitHub Action sends a build hook to Netlify to trigger a new build of the staging site.

For an example of these GitHub Actions, see the IMDG documentation repository.

Contributing

To learn how to use the playbook and generate the docs site locally, see our contributing guide.

hazelcast-docs's Issues

Broken link to staging in the README

Description

The correct link to the staging site is stored in the url-staging attribute, however GitHub seems to change the URL, which results in a 404

Expected

GitHub opens the correct url

Additional context

Add any other context about the problem here.

/latest results in 404 in the side nav

Description

If you come to the site with just the URL docs.hazelcast.com/imdg/latest, you get the index page, which is correct. But then if you click a link in the side navigation, you get a 404.

Expected

The sidenav links should resolve to the latest version.

Additional context

Add any other context about the problem here.

Minor Suggestion: Rename Tutorials link

A first coming user to https://docs.hazelcast.com/ would click on the Tutorials directly and expect Tutorials to be about how to do simple stuff with pure Hazelcast.

But our Tutorials page is related to integration modules only.

We could rename it "integration tutorials" or similar, and maybe put it afterwards "getting started" link?

Allow users to input their own server URL in swagger

Describe the solution you'd like

Users should be able to input their own server URL in the Swagger docs so that they can use the 'Try it now' button.

This is an open issue in the Swagger UI repo: swagger-api/swagger-ui#4735

Additional context

We temporarily removed the 'Try it now' button until this feature is implemented: ca14728

Suggestion: hazelcast versions should be more accessible

Is your feature request related to a problem?

jumping between version of the current page takes too many clicks here and there.

Describe the solution you'd like

postgres documentation is a good example (just one click at links at the top of the pages).

https://www.postgresql.org/docs/13/tutorial-join.html

Some minor issues in POC

As I have been working on the redirection matter, my 2¢:

• Distributed Object Events section: Right side navigation only includes “Listening for Map Events”
• "Undefined" labels: I see some “undefined” labels with “copy to clipboard” buttons under some code blocks (https://jakescahill.github.io/docs-poc/imdg/latest/events/object-events.html#catching-a-map-event). I am guessing this happens when the source code language is not provided while writing the code blocks in adoc files. PS: I can work on the source content to provide the required source code language attributes.
• White space: It maybe a minor cosmetic issue but the white space to the left of TOC seems a bit wide.