Skip to content

lib/gis: Quote YAML description in parser --md-description output#7528

Merged
echoix merged 2 commits into
OSGeo:mainfrom
petrasovaa:escape-yaml
Jun 13, 2026
Merged

lib/gis: Quote YAML description in parser --md-description output#7528
echoix merged 2 commits into
OSGeo:mainfrom
petrasovaa:escape-yaml

Conversation

@petrasovaa

@petrasovaa petrasovaa commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Closes #5907
Closes #5841
Problem:
image

The --md-description frontmatter emitted the description: value as an unquoted YAML. When a tool's label or description contains ": " (colon followed by space), YAML reads it as a nested mapping key and the frontmatter fails to parse, breaking the MkDocs page. r.viewshed is one example ("Default format: NULL ...").

This quotes the description value and escapes any embedded \ and ", so descriptions with colons (or quotes) produce valid YAML. Fixes the rendering for every affected tool, not just r.viewshed.

Tested locally, coded with AI.

@github-actions github-actions Bot added C Related code is in C libraries labels Jun 10, 2026
@petrasovaa petrasovaa changed the title lib.gis: Quote YAML description in parser --md-description output lib/gis: Quote YAML description in parser --md-description output Jun 10, 2026
echoix
echoix previously approved these changes Jun 10, 2026

@echoix echoix left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's try this, when merging, find the two other PRs and the issue to close at the same time. I think they re not linked yet. One PR was from Corey I think.

@echoix

echoix commented Jun 10, 2026

Copy link
Copy Markdown
Member

Finally, your PR is not really different than #6270, that still misses situations that will happen as described in #5841. Maybe the ai will come up with a better implementation when pointed at what cases to fix and the general direction like I had written

@petrasovaa

Copy link
Copy Markdown
Contributor Author

Finally, your PR is not really different than #6270, that still misses situations that will happen as described in #5841. Maybe the ai will come up with a better implementation when pointed at what cases to fix and the general direction like I had written

I totally forgot about all these... I need to review all the linked PRs/issues.

@petrasovaa

Copy link
Copy Markdown
Contributor Author

Added stripping the quotes and undo the backslash escaping when building the tool index and topic pages so they no longer show literal quotes around descriptions.
This solution seemed simpler than reading the | syntax in Python.

@github-actions github-actions Bot added Python Related code is in Python docs labels Jun 10, 2026
@petrasovaa petrasovaa requested a review from echoix June 12, 2026 17:53

@echoix echoix left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let’s try that, and see if we miss some syntax somewhere

@echoix echoix merged commit d078b30 into OSGeo:main Jun 13, 2026
26 of 28 checks passed
@github-actions github-actions Bot added this to the 8.6.0 milestone Jun 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

C Related code is in C docs libraries Python Related code is in Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] Colon in parser description field generates invalid markdown header

2 participants