Asciidocs and refdocs tooling

[balopat]

This is in context of #629.

See generated example:

• HTML: https://storage.googleapis.com/balint-skaffold/docs/index.html
• PDF: https://storage.googleapis.com/balint-skaffold/docs/index.pdf

Documentation tooling requirements:

• Written in a format that is renderable on Github
• Content is accessible through an outline (sidebar preferably)
• Enables easy PR workflows
• Easy to review changes
• Easy for a contributor to propose changes

Additional goals:

• Composable pages to reduce duplication
• Ability to style/brand
• Satisfy the following layout goals:

Layout goals:

• Have a great, searchable single page HTML with a clear outline (the same for the PDF)
• Support Github as a renderer
  • Have a full Github landing page (just like currently)
  • The examples would still live in their separate folders as standalone documented examples, with a good Github specific README with table of contents
• Keep duplication minimal
  • The first chapter of the reference docs would come mostly from the Github landing page
  • Examples would be included in the reference docs

[dgageot]

Nice!

[r2d4]

Hide these from the github preview if you can

[dgageot]

Sorry @balopat, you have to rebase

[r2d4]

this fails @balopat
docker is not in the integration test image. I would move this to a separate step (I don't want to add asciidoctor to the integration/published skaffold image

[balopat]

sounds good. I'll fix it up.