sphinx-contrib / sphinx-contrib/openapi

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

Open Beginner friendly
#173 0 comments 0 reactions 0 assignees View on GitHub

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.