sphinx-contrib / sphinx-contrib/openapi
Old renderer with :request: emits a sourcecode block without a trailing blank line, warning under -W
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 126
- Forks
- 88
- PR merge metrics
- No merged PRs in 30d
Description
When the old (default) httpdomain renderer is used with :request:, it emits a .. sourcecode:: json block for the request body and then the next field with no blank line between them. That's invalid reStructuredText, so docutils warns. Under sphinx-build -W the warning is fatal, which makes :request: unusable for projects that build with warnings as errors.
Minimal reproducer
spec.yml:
openapi: 3.0.3
info:
title: Minimal
version: 1.0.0
paths:
/thing:
post:
summary: Create thing
requestBody:
content:
application/json:
schema:
type: object
properties:
name:
type: string
responses:
200:
description: Created.
index.rst:
Page
====
.. openapi:: spec.yml
:request:
conf.py:
extensions = ["sphinxcontrib.openapi"]
Actual
$ sphinx-build -W -b html src out
src/index.rst:15: WARNING: Explicit markup ends without a blank line; unexpected unindent. [docutils]
Build fails (exit 1). Without -W it's a warning and the page still renders.
Expected
No warning. The generated markup should be valid reStructuredText.
Cause
In sphinxcontrib/openapi/openapi30.py, the request-body branch emits the directive and its content but never a closing blank line:
309: yield '{indent}**Request body:**'.format(**locals())
310: yield ''
311: yield '{indent}.. sourcecode:: json'.format(**locals())
312: yield ''
313: for line in req_properties.splitlines():
314: # yield indent + line
315: yield '{indent}{indent}{line}'.format(**locals())
316: # yield ''
The next thing yielded is the :status ...: field at the outer indent level, so docutils sees the directive body end without a blank line and reports the unindent.
Note line 316: the yield '' that would close the block is present but commented out. Compare the response-example path around lines 244-248, which does emit a trailing blank line and doesn't produce this warning:
244: yield ''
245: for example_line in example['value'].splitlines():
246: yield '{extra_indent}{indent}{example_line}'.format(**locals())
247: if example['value'].splitlines():
248: yield ''
So the fix looks like emitting a single blank line after the request-body loop, mirroring that pattern. I'm happy to open a PR if that's the direction you'd want.
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/openapi30.py around the request-body branch at lines 309-316, then compare it with the response-example path around lines 244-248. Run the minimal reproducer with sphinx-build -W; done means the generated request-body markup produces no docutils warning and the build succeeds.
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
- 90/100