Process for auto-documenting OCIS_ (global scope) env vars

[mmattel]

Similar to have a documention process for env vars for services, we need a process documenting ALL OCIS_env vars as they have by design a global scope. One of the challenging issues is, that there are OCIS_ env vars which are not mentioned in any service and therefore not visible in any documentation. This documentation is necessary as else the purpose of those global envs gets lost and no overview is present.

There was already an intense discussion with @dragonchaser @wkloucek including a solution proposal that not only would work for the ocis and the docs-ocis repo, but also being future proof.

This issue is necessary to have the requirement documented and as a reference of the upcoming solution.

@micbar fyi

[dragonchaser]

Proposal workflow:

Scan code (e.g. grep -R os.GetEnv) => Generate a yaml with the variables and its type but leave the description empty => Descriptions are manually filled by the docs team => generate adoc template for consumption

With every subsequent run, the generated yaml from the previous run is consumed beforehand, existing variables in that yaml are not updated, because they have already been edited by the docs team. With that approach it would also be possible to manually add variables that are either not present in the code directly or are consumed through os.GetEnv

Proposal yaml structure:

variables:
    - name: "OCIS_URL"
      type: "string"
      default: "some_default"
      description: "Base ocis URL"
      dependend_services:
        - name: "service_a"
          path: "filepath"
        - name: "service_b"
          path: "filepath"
      do_ignore: false
    - name: "OCIS_IDP_URL"
      type: "string"
      default: "some_default"
      description: ""
      do_ignore: false

[mmattel]

#3917 (Harmonize env variable naming for those which are not bound to a particular service)

[dragonchaser]

#3917 (Harmonize env variable naming for those which are not bound to a particular service)

IMHO It would make sense to tackle #3917 first.

[mmattel]

Found a env var by chance where the description is missing,
see issue: #4922 (OCIS_GRPC_TLS_ENABLED has no description in Auth Basic)

[kobergj]

Global envvars handled here: #5369