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?us...
--
Paul Wright
Mobile Docs (github: finp)