[aerogear-dev] Introducing Antora for publishing docs

[Paul Wright]

Hi

Up to now, I've been using asciibinder [1] to preview docs, but Dan 
Allen (of asciidoctor fame) has released Antora [2], which addresses our 
use case better, and I'd like to switch to using that.

Specifically, Antora is designed to work with:

* remote code repos where docs is written along side code

* multiple component versions (automatically provides menus to switch 
between versions)

We were trying to script around asciibinder to allow for those issues 
(remember asciibinder was written for OpenShift, a single product with 
multiple flavors, rather than a set of versioned services), however I 
think we can get further faster with Antora .

This won't affect the way you author adoc files (in fact it should make 
it easier), we'll just need to include a structure in each docs directory.

If you look at the Antora docs [2] you can see the system in action, the 
menu at the bottom left allows you switch between versions (currently 
only 1.0 is available), and a component (Antora Default UI). You'll also 
see that there's a link to 'Edit this Page' which will direct you to the 
correct repo and branch as required.

There are a lot of other advantages [3], but I've outlined the main 
ones, and created a rough rendering of what it means for AeroGear [4]

Let me know of any objections,

thanks,

Paul


[1] http://asciibinder.org/

[2] https://docs.antora.org

[3] https://antora.org/

[4] 
https://drive.google.com/file/d/1l4AJGKSLI2e7vy9emIkVNTojf-C1waFM/view?usp=sharing

-- 
Paul Wright
Mobile Docs (github: finp)