docs(cli): Add a long description for file render

[lena-larionova]

The existing description for deck file render doesn't currently provide any detail on what the command does or how to use it.
I was trying to test it out and couldn't even figure out how it was supposed to work, since there's no input file flag or example.

Found the info I needed on Slack here, and based the update on that: https://kongstrong.slack.com/archives/C04349E4KRC/p1690921140291889

❗ I did run into one potential issue while testing: this command doesn't warn you when overwriting existing files, like deck dump or others do. Is that intentional?

[rspurgeon]

cc. @zekth

[Tieske]

@zekth iirc this command also renders the files, as they would be synced to the control plane (kong or Konnect), such that it will also do substitutions etc. That is currently not in the description, should it be? including maybe a warning that secrets might be in the rendered file?

[zekth]

currently render use mocks for values, so secrets won't be rendered.

ref:

deck/file/reader.go

Line 36 in 20ef81e

func GetContentFromFiles(filenames []string, mockEnvVars bool) (*Content, error) {

deck/cmd/file_render.go

Line 24 in 20ef81e

true)

[rspurgeon]

@lena-larionova @zekth can we get this updated with the one suggestion (or something similar) and get it merged?

[lena-larionova]

this command also renders the files, as they would be synced to the control plane (kong or Konnect), such that it will also do substitutions etc.

How's this @Tieske @zekth :
Short description: "Combines multiple complete configuration files and renders them as one Kong declarative config file."

Then some questions about the rest:

currently render use mocks for values, so secrets won't be rendered.

Does this mean the rendered file isn't in a ready state for syncing to a control plane, as the user has to replace mocked values with their own? Or am I misunderstanding something.

such that it will also do substitutions etc. That is currently not in the description, should it be?

What should be said about substitutions? What's the etc part? Is that something we should list out? What exactly should we add to the long description here?

[Tieske]

currently render use mocks for values, so secrets won't be rendered.

Does this mean the rendered file isn't in a ready state for syncing to a control plane, as the user has to replace mocked values with their own? Or am I misunderstanding something.

No, the goal is to validate local, so users would not edit manually, but if successful do an actual sync with actual values (not mocked ones).

Deck does;

1. grab files
2. combine them
3. render variables and "other magic"
4. sync to CP

especially step 3 & 4 were a single operation, without an option to inspect the output of step 3. The new render command allows a user to execute the same steps, but without the sync, so they can validate locally. (otherwise the user would need a running Kong system to test the sync against)

such that it will also do substitutions etc. That is currently not in the description, should it be?

What should be said about substitutions? What's the etc part? Is that something we should list out? What exactly should we add to the long description here?

Above I named it "other magic" because I do not know exactly what deck logic is executed here. Probably @GGabriele knows. If there is any additional logic, and if so, what it exactly is.

[rspurgeon]

I think my suggestion above covers enough of the use case here to apply it and merge this down

[rspurgeon]

left a suggestion

[lena-larionova]

@zekth @Tieske Added Rick's suggestion, how does that look?

Also added the term "render" back into the short description. That makes the description a bit long - is there a character limit I need to be aware of?

[rspurgeon]

LGTM

[zekth]

thanks

[codecov-commenter]

Codecov Report

Patch coverage has no change and project coverage change: -0.05% ⚠️

Comparison is base (6336929) 33.78% compared to head (2e2a096) 33.74%.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1007      +/-   ##
==========================================
- Coverage   33.78%   33.74%   -0.05%     
==========================================
  Files         101      101              
  Lines       12360    12375      +15     
==========================================
  Hits         4176     4176              
- Misses       7775     7790      +15     
  Partials      409      409              

Files Changed	Coverage Δ
cmd/file_render.go	0.00% <0.00%> (ø)

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.