sphinx-contrib / sphinx-contrib/openapi
httpdomain renderer: block-scalar summary produces unpaired ** and literal asterisks in output
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 126
- Forks
- 88
- PR merge metrics
- No merged PRs in 30d
Description
The httpdomain renderer wraps an operation's summary in ** without stripping it first. When the summary comes from a YAML block scalar the value ends in a newline, so the generated markup opens the strong marker on one line and closes it on the next. docutils can't pair it, and the reader sees literal ** on the rendered page.
This is a rendering defect, not just a warning: the asterisks are visible in the HTML output.
Minimal reproducer
spec.yml — note summary: |:
openapi: 3.0.3
info:
title: Minimal
version: 1.0.0
paths:
/thing:
get:
summary: |
Get Thing
responses:
200:
description: A thing.
index.rst:
Page
====
.. openapi:: spec.yml
conf.py:
extensions = ["sphinxcontrib.openapi"]
openapi_default_renderer = "httpdomain"
Actual
$ sphinx-build -W -b html src out
src/index.rst:3: WARNING: Inline strong start-string without end-string. [docutils]
The rendered HTML contains a docutils problematic node with the literal marker:
<dd><p><a href="#id1"><span class="problematic" id="id2">**</span></a>Get Thing
Changing the spec to a plain scalar, summary: Get Thing, makes the warning and the literal ** disappear. That's a viable workaround, but a block scalar is valid YAML for this field and shouldn't break rendering.
Expected
**Get Thing** rendered as strong text, with no warning, regardless of trailing whitespace in the source value.
Cause
sphinxcontrib/openapi/renderers/_httpdomain.py, line 284:
284: yield f" **{operation['summary']}**"
With operation['summary'] == 'Get Thing\n' this yields:
**Get Thing
**
.strip() on the value before interpolation should be enough. Description fields don't have this problem because they go through the markup converter, which normalizes them; summary is interpolated directly.
Worth noting the old renderer handles the same spec without this warning, so it's specific to this renderer.
Happy to open a PR for the .strip() if you'd like.
Environment
- sphinxcontrib-openapi 0.9.0
- sphinxcontrib-httpdomain 2.0.0
- Sphinx 8.2.3
- docutils 0.21.2
- Python 3.12.13
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start in sphinxcontrib/openapi/renderers/_httpdomain.py at the summary interpolation around line 284, then reproduce the issue with the provided spec.yml, index.rst, and conf.py. Run sphinx-build -W -b html src out and confirm the block-scalar summary renders as strong text without a warning or literal asterisks, while the existing plain-scalar behavior remains unchanged.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 85/100