/training-v3

(new) Neo4j Training Material

Primary LanguageJupyter Notebook

Neo4j Training Material

GitHub Actions Status

This repo will use the Gradle tool chain for building the following for Courses:

  • HTML for online courses

  • HTML for enrollment pages

  • HTML for reveal.js slide presentations

  • PDF

This repo will use the Gradle tool chain for building the following for Browser Guides:

  • HTML Neo Browser guides

  • PDF

Structure of the repo

  • modules each directory is a course or a browser guide which contains:

    • modules the modules list of the Antora documentation component (contains AsciiDoc source files)

    • docs the AsciiDoc source files

    • images the images

    • single-pdf container for generating the course guide or exercise guide

    • single-slides container for generating a single HTML for the entire course

    • build generated when you convert AsciiDoc which contains these important artifacts

      • enrollment the HTML for the enrollment page

      • online the online HTML and the PDF for each lesson of the course

      • slides the HTML slides for each lesson of the course

      • single-pdf the PDF for the course guide or exercise guide

      • single-slides the HTML slides for the entire course

Prerequisites

Since we are using the Gradle Wrapper, the only requirement is to have Java installed.

A Java version between 8 and 13 is required to execute Gradle. Java 14 and later versions are not yet supported.

Using the Gradle Wrapper

On Windows, open a terminal and type:

$ gradlew.bat

On Linux and macOS, open a terminal and type:

$ ./gradlew

If you run this command for the first time it will download and install Gradle. Make sure that you have an unrestricted access to Internet (ie. not behind a corporate proxy).

Tasks

In the following examples, we are going to use the command ./gradlew. If you are using Windows, don’t forget to replace ./gradlew by gradlew.bat.

Convert to HTML
$ ./gradlew convertOnlineHtml
Convert to PDF
$ ./gradlew convertOnlinePdf
Convert to reveal.js
$ ./gradlew convertSlides

All the generated files will be available at modules/{moduleName}/build.

If you want to convert all the files at once, you can use the convert task:

$ ./gradlew convert

You can also run a task on a specific module:

$ #./gradlew <nameOfModule>:<task>

For example:

$ ./gradlew 4.0-intro-neo4j:convertSlides
$ ./gradlew 4.0-intro-neo4j:convert

If you want to create a single slide deck for a group of slide AsciiDoc files, make a folder named "single-slides". In that folder include the AsciiDoc for the group of files you want to combine. (see example in 4.0-intro-neo4j module) Then use this command to build it:

$ #./gradlew <nameOfModule>:convertSingleSlides

There is similar functionality for consolidating PDFs. It uses the folder "single-pdf". The caution with generating a large PDF, however is memory. If you have a large PDF that you want to produce, you may need to install mogrify.

$ #./gradlew <nameOfModule>:convertSinglePdf

Gradle will do his best to detect if a task needs to be run again or not. If you want to force Gradle to execute a task again, you can remove the build directory using the clean task:

$ ./gradlew clean

Once the build directory is removed, type the task you want to execute.

You can also clean a particular module which removes the build folder for that module:

$ #./gradlew <nameOfModule>:clean

LiveReload

To enable LiveReload, you will need to install the LiveReload browser extension on Chrome. Once it’s done you should have a new icon on the right of your address bar:

livereload icon

Next, you need to open two terminal. In the first one, type the following command to continuously convert the AsciiDoc source to a reveal.js presentation:

$ #./gradlew --continuous <nameOfModule>:convertSlides

On the second one, type the following command to start the LiveReload server on the demo module:

$ #./gradlew <nameOfModule>:liveReload

> Task :liveReload
Enabling LiveReload at port 35729 for /path/to/modules/demo/build

You’re all set!

Now, open Chrome and navigate to the HTML file of your choice, for instance: http://localhost:35729/slides/04_IntroductionToCypherPresentation.html. Don’t forget to enable the LiveReload extension on your browser by clicking on the icon:

livereload enabled

Notice that the middle circle is now filled in black.

If you edit the corresponding AsciiDoc source (or resources), and wait a few seconds, your browser will automatically be refreshed with your changes.

Add a new module

To add a new module, edit the settings.gradle file at the root of this project. For instance, if we want to add a new module named `browser" located at modules/browser-guides, we need to add the following lines:

include 'browser'
project(':browser').projectDir = file('modules/browser-guides')

Now we can execute tasks on this new module, for instance:

$ ./gradlew browser:convert

Viewing slides locally

  1. In a terminal window, navigate to the folder where the slides HTML resides, for example:

    cd modules/demo/build/slides
  2. Open the an HTML page in JS-enabled Browser

    • ESC to see summary slides

    • Page down/Page up to move from slide to slide

    • Option + Click to zoom in/zoom out

    • S to open speaker notes in a different window

Antora Local preview

As a prerequisite, you will need to install the latest LTS of Node.js. Once node and npm are installed, open a terminal and type:

$ npm i
$ npm i --prefix resources/site-generator

The above commands will install the dependencies.

Tasks

Build and publish the site in public directory:

$ npm run build

Start a local server to serve the public directory:

$ npm run start

Continuously watch, build and serve the site:

$ npm run watch
💡

It can take quite some time to build all the courses everytime. To get a snappier experience, we recommend using the envrionment variable TRAINING_MODULE to build only one course. For instance, if we are working on the datascience course:

$ TRAINING_MODULE=datascience npm run watch