Add initial Dockerfile

[dontlaugh]

This is a simple take on a docker build that uses the rakudo base container.

Test from the root of the directory like this

docker build -t localhost/rakuast-rakudoc-render:latest .

The podman executable can be used instead of docker, as well.

Details on usage are TBD, but it will involve users mounting their source code inside as a volume mount.

[dontlaugh]

What would cause this error?

Failed to open file /opt/rakuast-rakudoc-render/resources/compliance-rendering/rakudociem-ipsum.rakudoc: No such file or directory

[dontlaugh]

This installs dependencies via zef, but it doesn't quite work yet as a "containerized executable" for the bin/RenderDocs script.

It would also be good if you could modify your assumptions in the multi sub MAIN that accepts two parameters. Specifically here

render-files([$file,], '.', :$to)

We need to be able to accept absolute paths here and not make assumptions about the names of directories, where they're run, names of input files, etc.

For example, I cloned your example rakudoc repo and ran this

podman run -w /opt/rakuast-rakudoc-render -v $PWD:/src --rm localhost/rakuast-rakudoc-render:latest RenderDocs /src/docs/README
Processing ｢.//src/docs/README.rakudoc｣ to ｢/src/docs/README.md｣
Could not open .//src/docs/README.rakudoc. Failed to stat file: no such file or directory

/src/docs/README.rakudoc is a valid path in the container because I've mounted it there. But it's unclear how to target it.

[finanalyst]

@dontlaugh These errors are occurring because of ad hoc links that I have not eliminated.

1. rakudociem-ipsum.rakudoc is from Raku/RakuDoc-GAMMA and is changing as I find corner cases to be checked.
   • There is an executable bin/get-compliance in this repo that pulls the file from the Raku/RakuDoc-GAMMA repo.
   • I should use one of the git commands, such as submodule or subtree, but I haven't quite got it working.
2. Understood about the assumptions on the paths/names of sources.
   • render-files was thrown together quickly.
   • I created one callable to render things into .md, and another into .html They probably should be the same with different flag, say --format='md'
3. however, I would prefer to have defaults that can be overriden. So, would you be happy with:
   1. the directory where the source files are located is by default $cwd/docs and can be specified by --src='/src'
   2. the directory where the .md files are written is $cwd and can be overridden by --to='/output-files'?
   3. If only one file is to be converted then it is named in the arguments.

This means that

• render-files without any arguments will take all the rakudoc sources in ./docs and render them into .md files in the cwd
• render-files --src='/src' will take all the rakudoc sources in /src and render them to the current working directory
• render-files --to='/output-files' will take all from './docs' and output to '/output-files'
• render-files SOME-random-name will only render that file in the default src and output to the default dir
• render-files --src='/src' --to='./somewhere/' filename uses all three

I'm just writing it all out fo flesh out the design. I think (!) the named parameters (eg. --src) have to come before the unnamed ones, in this case the filename.

[dontlaugh]

I like the "uses all three" variant for writing things like scripts and CI workflows, because when I revisit things like this in 6 months the flags are scriptive and help me understand what's going on.

[finanalyst]

@dontlaugh I'll rewrite. each variant can be used.