grafana / grafana/shared-workflows
generate-input-output-docs: multi-line code examples flatten into one table cell
- Dominant language
- Go
- Stars
- 26
- Forks
- 49
- Avg merge
- 1d 6h
- Merged PRs (30d)
- 36
Description
Reported by @zerok while reviewing #2276, as an inline comment on `actions/get-vault-secrets/README.md`:
> Looks like the renderer is struggling with new-lines there. It would be awesome if you/someone could fix this in a follow-up but it's not critical imo.
## What happens
`cleanCell` in `scripts/generate-input-output-docs/render.go` collapses every run of whitespace so a description fits on one line of a markdown table. When the description contains a fenced code block, that flattening destroys the thing the example exists to show.
`actions/get-vault-secrets/action.yaml` declares (fence indented here so it nests):
```yaml
repo_secrets:
description: |
Repository-specific secret mapping. ...
Ex:
```
repo_secrets: |
ENVVAR1=secretpath:key
ENVVAR2=secretpath:key2
```
```
and the generated cell renders as:
... Ex: `repo_secrets: \| ENVVAR1=secretpath:key ENVVAR2=secretpath:key2`
One pair per line is the whole point of the example, and it is gone. The `|` also has to be escaped to survive the table, which adds noise.
## Affected
- `actions/get-vault-secrets` — `repo_secrets`, `common_secrets`
- `actions/trigger-argo-workflow` — `parameters`. Already mitigated: the README carries a separate code block below the table showing the `key=value` per line convention.
## Options
1. Move such examples into hand-written prose outside the generated markers, the way `trigger-argo-workflow` already does. No generator change, but it relies on authors knowing to do it.
2. Have the generator detect a fenced block in a description, keep a short summary in the table cell, and emit the example as a real code block beneath the table. More useful, more machinery.
Option 2 is the better outcome if the extra complexity is acceptable.
Worth stating either way: a markdown table cell cannot contain a multi-line code block, so the example has to live outside the table. This is a question of where it goes, not of making the flattening lossless.
## Context
The generator and the CI drift check landed in #1454 and #2276. Nothing here blocks either — the affected cells are accurate, just less useful than the prose they replaced.
Contributor guide
Research direction
Start in scripts/generate-input-output-docs/render.go at cleanCell, then inspect the generated markers and the existing separate code block in actions/trigger-argo-workflow/README.md. Compare the affected descriptions in actions/get-vault-secrets/action.yaml and actions/trigger-argo-workflow. Done means multi-line examples no longer lose their per-line formatting in generated documentation, while the CI drift check remains accurate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100