grafana / grafana/shared-workflows

generate-input-output-docs: multi-line code examples flatten into one table cell

Open
#2,282 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.