Playbook Guide

The Playbooks repository serves as a compilation point for content from the Handbook and Blueprint repositories. As such technically there are no documentation that should be directly maintained in this repository. The content from the Handbook and Blueprint repositories are compiled and published into a website called "BigDoc", accessible only via 2 methods as follow:

BigDoc Google Drive

This "BigDoc" includes the content of both the "Public-Guide"(BigLedger Handbook) and "Private-Guide"(BigLedger Blueprint). In the future, we may also include documentation generated from the Java, Python and Angular codes.

The "Public Guide"(BigLedger Handbook) on it’s own, is also accessible by public via the following:

Cloning the Playbook repository

To get started, after you have access to the "Playbook" github repository, please "clone" the repository to your local environment:

Cloning playbook repository to your computer

You may organize the folders in your computer according to the following structure: * repo → the main folder with various repositories * bitbucket / github / gitlab → the repository hosting platform * ailedger / bigledger / akaun / wavelet etc…​ → the organization account in the repository hosting platform * Playbook / Private-Guide / Public-Guide → the repository name ** It is important to save the Playbook / Private-Guide / Public-Guide in the same folder, so that the scripts would work correctly.

Playbook folder structure

You may repeat the steps above for "Private-Guide" and "Public-Guide"

Playbook Folder Structure

Now, lets walk through each of the folder, and see how the files are organized.

Playbook "src" folder

Inside the "src" (we call it the "source" folder), you will see the following files:

  • bigdoc.yml

    • This is the single most important file you need to study.

    • When you open this file, you will see that we are including all the "components" into the website.

  • handbook.yml

    • This file is only used if we are compiling the "components" from Handbook only.

  • blueprint.yml

    • This file is only used if we are compiling the "components" from Blueprint only.

  • themes

    • We are storing the UI layout and themes of the website here.

Playbook "bin" folder

The only file that you will be using the most, would be bigdoc_build.sh. The content of the file is self explanatory from the source code below. We are just cleaning up the "build" folder from the previous compilation. And then we call the "npx antora" command to compile the website, using the bigdoc.yml in the previous section.

Finally, the third command would only works in Mac OS , which is to open up the results of the compilation in a web browser. If you are using Windows / Linux, to automatically open up the results, you may use a different variant of the file.

rm -rf build/*

npx antora --clean --asciidoc-sourcemap --stacktrace --fetch src/bigdoc.yml

open build/sites/bigdoc/index.html

Playbook "build" folder

This folder is excluded from the git repository. Every time a compilation happen, the output files will be stored in this folder. You may open up this folder to inspect the content, and see if it has been updated in accordance to your modifications.

Playbook "docs" folder

All contents in the docs folder would be published to the https://playbook.akaun.com/ . This would include the sub-folders. That means, if we were to make the blueprint accessible from https://playbook.akaun.com/12345/ We would be saving the output files in docs/12345/ folder.

Document Publishing Tools Setup

Setup Node JS

Node.js is a run-time environment that comes with everything you need to run a JavaScript programme. Before content is sent to a web browser, it is used to run programmes on the server to render it.

Node Package Manager, or NPM, is a tool and repository for creating and exchanging JavaScript code.

Refer to the following link for assistance in setting up Node.js, NPM, and other helpful Node.js commands on a Windows computer:

https://phoenixnap.com/kb/install-node-js-npm-on-windows/

Setup Antora

Please follow the setup steps in the following guide to ensure that pre-installation prerequisites are completed, remember to choose the latest versions here:

MacOS - https://docs.antora.org/antora/latest/install/macos-requirements/ Windows - https://docs.antora.org/antora/latest/install/windows-requirements/

Antora Installation Guide

Once you have completed the above pre-installation prerequisites, you may proceed with the installation steps of Antora :

https://docs.antora.org/antora/latest/install/install-antora/

Installing Asciidoctor

Installing Epub3 Converter

Please click on the link below for detailed instructions:

https://docs.asciidoctor.org/epub3-converter/latest/

Installing PDF Converter

https://asciidoctor.org/docs/asciidoctor-pdf/#install-the-published-gem

Installing Multipage HTML Converter

https://github.com/owenh000/asciidoctor-multipage

Playbook Compilation

Start by opening View > Terminal. Ensure that you are at the local Playbooks directory within the terminal. Then, execute the following command in the Terminal to start the Playbook compilation

bash bin/publish.sh

The above shell script will clean up the "docs" folder, recreate the "docs" folder, with images at the top level, and the rest of the "*.adoc" following its folder structure and then activate the antora to compiles all the files into the "docs" folder.

Refer to the following for more information: https://drive.google.com/file/d/1XAwdyqYxSXU7I2RJp9oO6L4EsgDTs1xX/view

Review Playbook

Once the compilation completed by the bin/publish.sh shell script, a local copy of the Playbook is compiled into the "build" folder. You may proceed to perform a self-review of the results by pointing your browser to "build/bigdoc/index.html"

The typical checkpoints are below, since they’re not able to be verified through vscode’s direct preview enabled by plugin:

  • Check that all the specific cross references using Antora tag "xref" are giving expected results

  • Check that all the image references using Antora tag "image" are giving expected results

Congratulations for reaching this far!!

Publish Playbook

This is final step to publish the compiled local copy of the Playbook externally on the playbooks website i.e. at http://playbook.akaun.com/bigdoc/index.html

1) Install AWS CLI:

If you haven’t already installed the AWS CLI, you’ll need to do so.You can download the installer for Windows from the official AWS CLI website: https://aws.amazon.com/cli/

2) Configure aws CLI:

  • Please ask for the AWS access key ID and secret access key details from Izzaty (Platform Services) and keep it confidential.

$ aws configure
AWS Access Key ID [****************6XHK]: *******************
AWS Secret Access Key [****************Wm7B]: ****************************************
Default region name [ap-southeast-1]: ap-southeast-1
Default output format [None]:

3) Run aws s3 sync Change directory to your local playbook folder then, run:

$ aws s3 sync ./docs/ s3://playbook.akaun.com --delete

Modify ./docs/ to the path of the local directory you want to sync.

Please check that all the expected changes are reflected correctly externally by pointing your browser to http://playbook.akaun.com/bigdoc/index.html