villebro opened a new pull request, #292:
URL: https://github.com/apache/superset-kubernetes-operator/pull/292
## Summary
The generated API reference (`docs/reference/api-reference.md`) leaked HTML
`<br />` tags into the Description column, so wrapped Go doc comments
rendered
as awkward mid-sentence line breaks (e.g. *"forces a re-run of this` <br />
`task
and all downstream tasks"*). This was flagged in the #279 review. The root
cause is crd-ref-docs' stock markdown renderer, which turns every newline in
a
doc comment into a `<br />`. This PR adds a small awk post-processing pass to
the `docs-api` pipeline that collapses those breaks back to spaces so
descriptions read as flowing prose.
The Validation column is deliberately left untouched: there `<br />` stacks
distinct constraints (`Minimum` / `Maximum` / `Optional` / ...) on their own
lines, which reads well and is intentional.
## Details
- **`hack/collapse-description-br.awk`** (new) — splits each member-table
row on
`|` and collapses `<br />` (with surrounding spaces) to a single space in
every cell *except* the Validation column (the second-to-last field). Enum
tables have no Validation column, so all their content cells are collapsed.
Cells never contain a literal `|` (crd-ref-docs escapes pipes, and none
occur
in practice), so field splitting is unambiguous.
- **`Makefile`** — `docs-api` now pipes crd-ref-docs output through the
existing
link-rewrite `sed` *and* the new awk pass.
- **`docs/reference/api-reference.md`** — regenerated.
awk rather than extending `hack/fix-api-ref-links.sed`: distinguishing
description breaks from validation breaks is per-column logic, which sed
can't
express cleanly, whereas awk's field splitting makes it a one-liner.
Generation is idempotent (`make codegen` is a no-op on a clean tree), so CI's
`Verify codegen` job stays green.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
