japila-books/apache-beam-internals

The Internals of Apache Beam

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.