Fix #173: strip whitespace from operation summary before rendering - #174
Open
dstrodtman wants to merge 1 commit into
Open
Fix #173: strip whitespace from operation summary before rendering#174dstrodtman wants to merge 1 commit into
dstrodtman wants to merge 1 commit into
Conversation
Collapse whitespace in operation summary before rendering it in bold A summary taken from a YAML block scalar keeps its trailing newline, so interpolating it produced an opening ** on one line and a closing ** on the next. docutils could not pair them, warned about an inline strong start-string without end-string, and rendered literal asterisks. Splitting and rejoining on whitespace also folds a multi-line summary onto one line, which keeps the continuation from breaking out of the directive body's indentation. Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #173.
The
httpdomainrenderer interpolates an operation'ssummaryinto**...**as-is. A summary written as a YAML block scalar keeps its trailing newline, so the opening**lands on one line and the closing**on the next. docutils can't pair them, warnsInline strong start-string without end-string, and the literal asterisks show up in the HTML.The issue suggested
.strip(), which is enough for the reported case. I used' '.join(summary.split())instead, since it also covers a literal block scalar spanning multiple lines —.strip()leaves that one emitting**Create\nan evidence.**, which produces the same warning and the same visible asterisks. For a plain or folded scalar the output is identical to.strip().To be precise about that second case, since an earlier revision of this description overstated it: it is a warning, not an error, and the document structure survives. I checked the pseudoxml — the directive's
desc_contentstill contains both the summary paragraph and the Status Codes field list, so the unindented continuation line does not escape the directive. It renders aproblematicnode with literal**exactly like the reported case. So the argument for whitespace-collapsing over.strip()is that it fixes one more shape of the same defect, not that the other shape fails harder.descriptiondoesn't need this because it goes through the markup converter, which normalizes it already.Two regression tests are added alongside the existing
test_render_operation_summary, one per case; both fail before the change. I kept them separate rather than folding them together, since the single-line block scalar is the shape the issue reports and the multi-line one is what motivates going past.strip().The committed renderer fixtures under
tests/renderers/httpdomain/rendered/are unchanged, since none of the example specs use a block-scalar summary — I confirmed that by runningpytest --regenerate-rendered-specs tests/and getting no diff.Scope note: this is the
httpdomainrenderer only, matching the issue. The old renderer splits the summary on newlines and emits**{line}**per line, so it cannot produce an unpaired marker.For context on where this turned up: the Ray docs are moving their Jobs API reference onto this extension, and currently have to constrain operation summaries to plain scalars to avoid the literal asterisks.