Che: Create/generate che-server configuration documentation

[skabashnyuk]

Is your task related to a problem? Please describe.

At this moment we don't have a single place in official documentation that has a complete list of available configuration options.

Describe the solution you'd like

We can use

• https://github.com/eclipse/che/blob/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che/che.properties
• https://github.com/eclipse/che/blob/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che/multiuser.properties
• https://github.com/eclipse/che/blob/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che_aliases.properties
  to generate doc with configuration. We already have here explanation of what property is and default value. I don't see reasonable effective to duplicate that information.

Describe alternatives you've considered

Duplicated documentation.

Additional context

n/a

[slemeur]

cc @themr0c and @rkratky : On this one, it would be very interesting that we find a way so that the documentation that is generated in the code could be reused in the project-documentation as well, this way we would have:

• a single place to edit those information
• consistent information

[themr0c]

This file is also a source of truth for something that should land in the documentation: https://github.com/eclipse/che-operator/blob/master/pkg/apis/org/v1/che_types.go

What we need is:

• The list of sources of truth in che codebase

• The destination for each of these sources in the documentation

• As our input is not natively supported by asciidoc, we will need to transform these files into something natively supported by asciidoc.

• Let's define how we want to present the content in the documentation:

• Integrating the files verbatim is probably not what we want.

• Does a three columns table "Property | Default value | Description" make sense? See: https://www.eclipse.org/che/docs/che-7/advanced-configuration-options/ https://github.com/eclipse/che-docs/blob/master/src/main/pages/che-7/installation-guide/ref_che-configmaps-fields-reference.adoc

• If we agree on tables: asciidoctor has native support for tables in CSV or DSV format, see https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#tables. (No YAML, no JSON, no INI, no Jinja, sorry, asciidoc is not a templating language).

• So, if we agree on tables, what we need is a script that transforms each source of truth into a CSV or a DSV file.

• And then we need to decide when to call that script: at build time (for each build?) or via a PR when the source file is changed? (I believe the second option should be sufficient)

• And probably, on the way, we will feel it necessary to modify the source files to make them easier to parse if we want to use them as a template source. (Current situation with unstructured multi-lines comments is not optimal)

[skabashnyuk]

@themr0c you absolutely right about multiple sources of truth that we have at this moment.
I propose to limit the scope of this issue only by che-server and at least get some ideas on
how we want to document that. Later I think with the help of @tolusha we can extend it to the multiple ways on how we are deploying che.

Does a three columns table "Property | Default value | Description" make sense?

yes + Che server also has a concept of an alias. Alias is an alternative way to name a variable.

aciidoctor has native support for tables in CSV or DSV format

CSV is ok for me.

So, if we agree on tables, what we need is a script that transforms each source of truth into a CSV or a DSV file.

ok

And then we need to decide when to call that script: at build time (for each build?) or via a PR when the source file is changed? (I believe the second option should be sufficient)

We propose to do that on build time.
During build we will

• Take the version of che docs from pom.xml. download che.api.war(for example https://oss.sonatype.org/content/repositories/snapshots/org/eclipse/che/assembly-wsmaster-war/7.6.0-SNAPSHOT/assembly-wsmaster-war-7.6.0-20191213.123751-44.war)
• take all resources with default values
• generate appropreate csv file

[themr0c]

I agree with all of that @skabashnyuk. Sounds really great!

Is it possible to have the script be written with as few dependencies as possible. Meaning: using only POSIX shell or bash?

We have 2 builds for the documentation: one to build a war to embed in Che, one to publish the website.

To publish the website we are not using ant, and not using pom.xml. We are using a container with no ant, no java in it, and we would like to keep it like that. We currently needed to bake our own container. In the future we would like to use directly the official container proposed by antora, and not adding additional dependencies is a requirement for that.

[mshaposhnik]

So I started writing an bash script which is:

• Looking at the version in the che-docs pom (everything that ending with -SNAPSHOT treat as master)
• Grabs the raw che.properties and multiuser.properties content from github using master or tag version
• Parses content into topics and creates csv-based tables for each individual topic
  So at the end we have .adoc which can be processed with asciidoctor to get the HTML page.
  This is how the testing page looks ATM:

[sleshchenko]

@mshaposhnik Actually, a user has no opportunity to configure a value for the configuration property with its original name. Then maybe it's better to print the corresponding environment variable name (upper case, _ -> __, . -> _) like CHE_SERVER_SECURE__EXPOSER for che.server.secure_exposer?

[mshaposhnik]

@sleshchenko I would rather add an extra column for that, WDYT ? @skabashnyuk @slemeur

[slemeur]

It's very important to properly explain to the end-user where and how those values can be configured. In the screenshots I see (and they might not show everything), there is no mention about where those are defined.
So:
1- make sure that the user understand where those values can be changed/updated
2- Provide the proper property name (or env variable) that needs to be used. (I'm +1 for adding another column to make it clearer and more comprehensive)

[themr0c]

It looks really great. I believe automating the generation of the properties tables and explaining how to use them can be kept as separate issues.

There will be some formatting to do at some point (now or in a later step?).

[mshaposhnik]

I think i do my best for the moment. I left only the ENV names since if keep both property and ENV, tables became too wide. here is the diff https://github.com/eclipse/che-docs/pull/1041/files and preview is at https://mshaposhnik.github.io/