Missing documentation about knobs (ENV vars)

[vorburger]

While working on quarkusio/quarkus-quickstarts#81, I hit:

WARN ARTIFACT_COPY_ARGS is deprecated.  Please use S2I_SOURCE_DEPLOYMENTS_FILTER to specify artifact types and MAVEN_S2I_ARTIFACT_DIRS to specify the build output directories to copy from.

When looking at this repo for doc (something like this doc over here) I could not find any list of supported environment variables with explanations.

The "product" documentation, which is based on this community project, does not seem to have such documentation either?

Googling let me find https://github.com/jboss-openshift/cct_module/blob/master/jboss/container/s2i/core/api/README.adoc and https://github.com/jboss-openshift/cct_module/tree/master/jboss/container/maven/s2i/api but, to an end-user, it is not clear how those module docs in separate repos relate to this project (and what other ones there are).

Perhaps we could improve the README? Either with appropriate links, or copy/paste.

@tqvarnst @siamaksade

[jmtd]

Cekit used to have a feature that generated documentation on the aggregate of modules that an image uses (c.f. cekit/cekit#268 (comment))) but I think it did not survive the refactor in Cekit 3.x so we need to bring it back, run it, and commit the results in this repository.

Although I am having trouble finding reference to the old feature, I might be mixing it up with container help pages which aggregate (some) of the API stuff from modules and put them into a specifically-formatted markdown file designed for inclusion within the images that are built. So not quite the same.

[jmtd]

OK I've just hacked together a script that does what cekit (or something else) used to do:
https://github.com/jmtd/openjdk/tree/gendocs
example output
https://gist.github.com/jmtd/5410196d3fbef32ef3a090c8857ac209
I'm now thinking about where to publish something like this and how to automate its generation

[jerboaa]

@jmtd This is great!

[jmtd]

Thanks! I've generated four pages for the four OpenJDK images and put them here, temporarily

https://jmtd.net/tmp/openjdk-container-docs/

[jmtd]

I've just remembered that recent builds of the containers have a file /help.md in the root of the filesystem which is auto-generated (according to some restrictive specification I cannot recall) and this contains a complete list of the configuraton ENV vars. It's raw markdown, which does not have table support, so it's unwieldy to read, but it's a start: https://jmtd.net/tmp/openjdk-container-docs/help.html

We could possibly tweak it to use HTML tables, anything that accepts markdown should accept a subset of raw HTML too, I think.

[jmtd]

I'd like to think we've finally resolved this with the auto-generated material at https://jboss-container-images.github.io/openjdk/

that material can certainly still be improved!

[jerboaa]

I'd like to think we've finally resolved this with the auto-generated material at https://jboss-container-images.github.io/openjdk/

that material can certainly still be improved!

@jmtd We should add a reference to this doc in the README.md file so that it's easily accessible. What do you think?

[jmtd]

@jmtd We should add a reference to this doc in the README.md file so that it's easily accessible. What do you think?

It's there -- two sentences above "How to build the images". Perhaps it should be more prominent...

[jerboaa]

Perhaps it should be more prominent...

Yes, please. I missed it. Perhaps a separate heading "API Documentation" or some such.