Using a docker image for the asciidoctor tools

[arichardson]

Why the new feature should be added

I can be quite difficult to install all the asciidoc dependencies (in the correct version) on some systems, so for example RISC-V documentation generally builds using a docker image with all tools pre-installed. I would be great if we could use a docker image for the preview generation.

As a workaround I currently have some scripts in $PATH that spawn docker for certain tools (but this makes the preview pretty slow since it's launching a new container for each tool invocation.

How the new feature should work

Add a config option for build docker image selection. When chosen, the build will run inside a docker container that has the source and output directories bind mounted.

My current workaround script looks like this:

#!/usr/bin/env python3
import os
import sys
import argparse
import subprocess

if __name__ == '__main__':
    parser = argparse.ArgumentParser()
    parser.add_argument("--input")
    parser.add_argument("--svg")
    args = parser.parse_args()
    docker_cmd = [
        "docker", "run", "--rm",
        "--mount", f"type=bind,source={args.input},target={args.input},readonly",
        "--mount", f"type=bind,source={args.svg},target={args.svg}",
        "riscvintl/riscv-docs-base-container-image:latest",
        "wavedrom-cli", "--input", args.input, "--svg", args.svg,
    ]
    print(docker_cmd)
    os.execvp("docker", docker_cmd)

[ahus1]

Thank you for suggesting this. I think the two approaches are incompatible. See below for how to optimize each approach.

For the setup you describe, I've seen projects packaging the following solution:

• Create a container which can mount a folder with sources
• Span a process in the container which scans for source file changes
• Provide the files on a web server so that it can be used in the browser
• Employ some live reload JavaScript so that the changes are published to the browser without the user's need to press refresh

You can find an example here https://docs.asciidoctor.org/maven-tools/latest/plugin/goals/http/ but I know it exists in different variants for different projects. The live reload technology is available as a standalone JavaScript dependency as well, see https://github.com/livereload/livereload-js?tab=readme-ov-file

This IntelliJ plugin takes a different approach: It customizes the AsciIDoc engine quite a bit to get a good editing experience. For example, you can click on the preview to jump to the include file that is show at the location the user clicked. This is integration is not possible when another process generates the PDF.

To generate the images for the example documentation at hand, users can switch to Kroki for diagram generation. There is a cloud public instance for Kroki, but users can also spin up local containers for Kroki to get faster response times and to avoid sending possible sensitive information to a public Kroki instance. See https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/preview/diagrams.html#kroki for more details. At the same time the current source uses data-uri to embed the images in the output file. This makes the preview quite slow.

So I suppose with some minimal changes and hints for the plugin one could get a good editing experience with these docs using the built-in functionality of the AsciiDoc plugin.

[arichardson]

Thank you very much for the detailed response, it does sound like it would be really difficult to use a docker container.

I had not tried the Kroki option before but it seems to fulfil all my current needs, thanks for pointing that out. I've filed #1541 to document the steps I used to run it locally with docker.

The new preview generation is a lot faster than my wrapper script, so the editing experience is pretty good now even without further optimization.

[arichardson]

I guess a nice enhancement would be to run the kroki container automatically, but that's probably a separate enchancement request, so I'm happy to close this issue since I've got a better workaround now 🙂

[ahus1]

Happy to hear this works for you. Thank you for the PR for the docs, which has now been merged.