Using Asciidoctor for Zipkin Documentation

[zeagord]

Zipkin documentation is comprehensive and have enough information. But sometimes i feel, i have to traverse to different repos to find what I need. I feel it will be better to have the documentation in Asciidoctor and provide a nice readable version to the users.

[codefromthecrypt]

I am supportive of this, but bearing in mind many know Markdown but not Asciidoctor, we will need support.

Can we have a couple volunteer asciinurses? Basically to help if folks struggle while transitioning.

[jorgheymans]

+1 for offering an aggregated version of the documentation, if this is what the ticket implies.

Will you auto-generate asciidoctor from markdown or how would this work ?

[zeagord]

AFAIK generating asciidoc from MD is little tricky everytime. I think we have to convert all the docs to asciidoc and then add new documentation in the asciidoc format.

[joschi]

AFAIK generating asciidoc from MD is little tricky everytime.

Just leaving this comment without further weighing in: Pandoc is able to convert Markdown (in various flavors) into AsciiDoc.

As an example I've taken the README.md file from the 2.5.0 tag and converted it from Markdown to AsciiDoc using the following command:

pandoc -f markdown -t asciidoc -o README.adoc README.md

The result can be seen in this gist: https://gist.github.com/joschi/7d1e18d2e3f78eea9a5ccce38d177da0

It might not work 100% perfect every time, but it's a huge timesaver if you intend to migrate to Asciidoctor.

As a final note, the authors behind Asciidoctor have started a new project called Antora which might prove useful for consolidating the documentation from multiple repositories into a single static documentation site.