Skip to content

Fix #173: strip whitespace from operation summary before rendering - #174

Open
dstrodtman wants to merge 1 commit into
sphinx-contrib:masterfrom
dstrodtman:doc-1516-strip-operation-summary
Open

Fix #173: strip whitespace from operation summary before rendering#174
dstrodtman wants to merge 1 commit into
sphinx-contrib:masterfrom
dstrodtman:doc-1516-strip-operation-summary

Conversation

@dstrodtman

@dstrodtman dstrodtman commented Aug 13, 2026

Copy link
Copy Markdown

Fixes #173.

The httpdomain renderer interpolates an operation's summary into **...** 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, warns Inline strong start-string without end-string, and the literal asterisks show up in the HTML.

paths:
  /thing:
    get:
      summary: |
        Get Thing

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_content still contains both the summary paragraph and the Status Codes field list, so the unindented continuation line does not escape the directive. It renders a problematic node 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.

description doesn'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 running pytest --regenerate-rendered-specs tests/ and getting no diff.

Scope note: this is the httpdomain renderer 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.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

httpdomain renderer: block-scalar summary produces unpaired ** and literal asterisks in output

1 participant