sphinx-contrib / sphinx-contrib/openapi

Old renderer with :request: emits a sourcecode block without a trailing blank line, warning under -W

Open Beginner friendly
#171 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

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

  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/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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.