The Internals of Apache Beam Online Book

The project contains the sources of The Internals of Apache Beam online book.

Toolz

The project uses the following toolz:

• Antora which is touted as The Static Site Generator for Tech Writers.

• Asciidoc (with some Asciidoctor)

• GitHub Pages

• Atom editor with Asciidoc preview plugin

• Docker to run the Antora image

It’s all to make things harder…​ekhm…​reach higher levels of writing zen.

Generating Book

In order to generate the book, use the commands as described in Run Antora in a Container.

Below are the steps to preview a local version of the book.

$ docker run -u $UID --privileged -v `pwd`:/antora --rm -t antora/antora local-antora-playbook.yml

Alternatively and my way of doing it is as follows:

$ docker run --entrypoint ash --privileged -v `pwd`:/antora --rm -it antora/antora

// Inside the container
/antora # antora version
2.3.3

/antora # antora local-antora-playbook.yml

In the end (while outside the container), open the local version of the book.

$ open .out/local/index.html

IMPORTANT: If your Antora build does not seem to work properly, use docker run …​ --pull. This resets your cache.

Upgrading Antora

Upgrading Antora is as simple as pulling the latest version using docker image pull (with no version specified which assumes latest).

$ docker image pull antora/antora

Not Sphinx?! Why?

Read Giving up on Read the Docs, reStructuredText and Sphinx.