Skip to content

Latest commit

 

History

History
246 lines (163 loc) · 11.5 KB

README.adoc

File metadata and controls

246 lines (163 loc) · 11.5 KB
Raw

Hazelcast Documentation Site

GitHub Workflow Status Netlify deploy status Build Production blue

Documentation prototype

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

Preview of the documentation site
Table of Contents

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:

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.

Preview of the home page

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:

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.

Links Checker

History

Previously each branch of each repo had its own check-links-playbook.yml for links-checker. The problem was, that for the correct links check check-links-playbook.yml should have contained the full list of all other repos and branches that have targets of the links from the current branch, and all repos and branches that have links TO the current branch. In other words - that file was complicated to maintain, so no one did, resulting in a wrong link check with many false negatives and positives.

Idea

We do care about broken links only in the context of the full production build. That’s why the only correct way to check links is using global antora-playbook.yml.

How it works now

The links checker workflow consists of the next steps:

  1. Check out the global antora-playbook.yml.

  2. Check out the local antora-playbook.yml.

  3. Modify content.sources from the global antora-playbook.yml (use correct syntax for current PR branch).

  4. Inject content.sources from the global antora-playbook.yml to the local one (for links check we need only that list, but we cannot reuse the whole global antora-playbook.yml, because it might contain some extensions or parts not runnable in the context of a docs repo).

  5. Run the links check and report the results.

For this to happen we have several common files in the hazelcast-docs repo

Table 1. Files for links checker
File Description

action.yml

Contains common parts of the links checker workflow

load-check-links-playbook.js

Responsible for modification of content.sources from the global antora-playbook.yml.

Each of the docs repos can just call the common validate action from its workflow.

uses: hazelcast/hazelcast-docs/.github/actions/validate@main

GitHub Actions

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

Table 2. 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.