Replacing local playbook.yml with ad-hoc previewer command

[akosma]

This PR replaces the local playbook.yml file with an ad-hoc previewer command based on a Docker image.

Developers can still make docs and preview their documentation in http://localhost:2020.

The vale related functionality is left unchanged.

[corvus-ch]

Nice one. Thanks

[tobru]

Great effort, here are a few comments:

• The Makefile is a generic one for the whole project, not just for docs. So I would suggest to prefix all commands which are doing stuff for documentation with docs-. For example make docs-serve, make docs-vale, ... This way it's very clear that these commands are solely for working with documentation stuff.
• make docs-open would be cool to have, calling either open or xdg-open, like discussed in the chat
  • Also do an echo "Documentation is available under http://localhost:2020/" when starting up the container, this way one can also just click on the link as most modern terminals discover URLs and make them clickable - as an alternative to make docs-open
• Move the code for the image vshn/antora-preview to GitHub and make sure it has an appropriate license
• All Project Syn tools should have a similar Makefile, all doing the same when calling make docs-XYZ. I haven't checked that in all the current open PRs though, but until now the commands weren't aligned. We might even make sure that all Antora based repositories are having the same make commands available, this helps with the muscle memory
• https://github.com/appuio/openshift4-docs/blob/master/Makefile -> This one also has support for Podman, running the container in rootless mode. Would be cool to also have this on all other Makefiles, again to make all the Antora based projects as similar as possible.

Let's discuss and address this points here, before we do a mass update of all other Antora based repos.

[srueg]

Maybe we could add all these docs-* targets to a antora.mk file to include in the main Makefile?
I fear that otherwise the main Makefile gets really bloated. It would also help to keep them in sync (i.e. also with module-sync at some point).

[akosma]

Well the harmonization of all Makefiles with the same style will be quite a bit of work, as some are use UPPERCASE all over the place, others not… etc. This should probably be a separate task?

For my part, I will update all the PRs with docs-serve and docs-vale tasks, and will move the project to Github.

[akosma]

Oh, and add a message in the antora-preview Docker image to remind the user to open a browser.

[akosma]

• Moved the code of the image to Github
• Uniform Makefile targets (docs-serve and docs-vale) in all PRs:
  • Replacing local playbook.yml with ad-hoc previewer command lieutenant-operator#100
  • Replacing local playbook.yml with ad-hoc previewer command lieutenant-api#79
  • Replacing local playbook.yml with ad-hoc previewer command commodore#165
  • Replacing local playbook.yml with ad-hoc previewer command documentation#85
  • Replacing local playbook.yml with ad-hoc previewer command #48 (this one)