Autogenerate docs for all envbuilder flags

[bpmct]

There are many flags in envbuilder.go that are not documented in the README. We should document this in a README or another place and make it auto-generated

[BrunoQuaresma]

@mtojek my plans for this task:

• Create a go script in /scripts/doc_envbuilder_flags.go that adds all the flags to the README.
• I'm wondering if tests can be ignored here since it is not a critical flow.
• Add a step in the CI to check if the README is updated with the latest flags.

Do you think these steps make sense?

[mtojek]

Sounds good to me! Only few comments:

/scripts/doc_envbuilder_flags.go - maybe go with a dedicated directory in case we add more scripts with multiple files, so /scripts/docsgen/main.go

I'm wondering if tests can be ignored here since it is not a critical flow.

Yeah I would assume so as in this case results, generated docs, could be reviewed manually in PRs.

Add a step in the CI to check if the README is updated with the latest flags.

Yes, must have.

[BrunoQuaresma]

The current Options structure looks like this:

type Options struct {
	// SetupScript is ran as the root user prior to the init script.
	// It is used to configure envbuilder dynamically during the runtime.
	// e.g. specifying whether to start `systemd` or `tiny init` for PID 1.
	SetupScript string `env:"SETUP_SCRIPT"`
}

From this current structure I can get the flag name: SETUP_SCRIPT and the type: string but I can't get the description as it is a comment. At first, I can see two options:

1. Create a tag called desc and add it to the option.

type Options struct {
	SetupScript string `env:"SETUP_SCRIPT" desc:"SetupScript is ran as the root user prior to the init script. It is used to configure envbuilder dynamically during the runtime. e.g. specifying whether to start 'systemd' or 'tiny init' for PID 1."`
}

This option doesn't require major code changes, but having the description as a single-line string can be difficult to read.

2. Create another type to encapsulate each option

type Option struct {
	Env string
	Description string
	Type interface{}
}

type Options struct {
	SetupScript Option{
		Env: "SETUP_SCRIPT",
		Description:  `
			SetupScript is ran as the root user prior to the init script.
			It is used to configure envbuilder dynamically during the runtime.
			e.g. specifying whether to start 'systemd' or 'tiny init' for PID 1
		`,
		Type: string,
	}
}

This would require extra changes to the envbuilder module, which in itself isn't a bad thing, but I want to avoid adding unnecessary complexity.

@mtojek thoughts?

[mtojek]

Ammar created coder/serpent to build nice CLI interfaces. If you need to adjust structures, I would recommend migrating to this project, and...

that matches solution no 2. with a separate property for description. Maybe consider building the docsgen for serpent as a new OSS project?

[BrunoQuaresma]

Ammar created coder/serpent to build nice CLI interfaces. If you need to adjust structures, I would recommend migrating to this project, and...

I like this idea 👍

that matches solution no 2. with a separate property for description. Maybe consider building the docsgen for serpent as a new OSS project?

I like this idea too, but I would make it a separate issue/milestone.

[BrunoQuaresma]

@mtojek taking a closer look at the envbuilder code, it looks like envbuilder was not intended to be a CLI 😅 so it might make sense to update its types internally.

[mtojek]

Technically yes, but you can map ENV variables to CLI flags 👍

[mafredri]

I'd be in favor of allowing all envbuilder settings to be adjusted with both flags and environment variables. This may also help in testing envbuilder functionality.

Also, if you're looking to parse Go source files @BrunoQuaresma, I'd recommend taking a look at: https://github.com/dave/dst. Utilizing that, you can get comments as well.

[mtojek]

I'd be in favor of allowing all envbuilder settings to be adjusted with both flags and environment variables. This may also help in testing envbuilder functionality.

This would be much simpler :)

Also, if you're looking to parse Go source files @BrunoQuaresma, I'd recommend taking a look at: https://github.com/dave/dst.

Please nooo ... :D

[BrunoQuaresma]

Ok, after some thought I'm going to play around with the idea of transforming envbuilder into a CLI using coder/serpent.

I will share my progress here over the next few days.