Fix #171: close the request body's sourcecode block with a blank line - #175
Open
dstrodtman wants to merge 2 commits into
Open
Fix #171: close the request body's sourcecode block with a blank line#175dstrodtman wants to merge 2 commits into
dstrodtman wants to merge 2 commits into
Conversation
Close the request body's sourcecode block with a blank line The old renderer emitted the `.. sourcecode:: json` directive for a request body and then the next `:status ...:` field with no blank line between them, so docutils reported explicit markup ending without a blank line and the build failed under -W. The blank line goes after the loop over the body's lines, mirroring the response example path. A commented-out `yield ''` was already sitting inside the loop, where it would have separated every line of JSON instead of closing the block. Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
The 3.0 and 3.1 renderers carry separate copies of the request body path, and both were missing the blank line, so fixing only the 3.0 one left every 3.1 spec using :request: failing under -W for the same reason. Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #171.
The old renderer emits the
.. sourcecode:: jsondirective for a request body and then goes straight on to the next:status ...:field at the outer indent, so docutils reportsExplicit markup ends without a blank line; unexpected unindentand the build fails under-W.This lands in both
openapi30.pyandopenapi31.py. The two files carry separate copies of the request-body path and both were missing the blank line, so fixing only the 3.0 one would have merged as a no-op for every OAS 3.1 user. Verified by building a 3.1 spec with:request:against the 3.0-only fix: still exit 1 under-Wwith the same warning. There's a regression test per renderer.One note on the
# yield ''I pointed at in the issue: it's inside the loop over the body's lines, so uncommenting it in place would put a blank line between every line of the JSON rather than closing the block. The blank line belongs after the loop, which is what the response example path at lines 244-248 does.I left it unconditional rather than guarding it the way the response path guards on
example['value'].splitlines().req_propertiescomes fromjson.dumps, which always returns at least{}, so the loop always emits at least one line and the guard would never be false here.Verified against the reproducer in the issue:
sphinx-build -Wexits 1 on master with that warning, and exits 0 with the change applied, on both 3.0 and 3.1 specs.There was no existing test covering the
:request:output, so these are the first —TestOpenApi3HttpDomain.test_request_bodyandTestOpenApi31HttpDomain.test_request_body, each pinning the full markup including the blank line before:status. Both fail before the change.openapi30.pyandtests/test_openapi.pyare excluded from the black hook, so I matched the surrounding'{indent}...'.format(**locals())style there and kept the diff to the one line per file;openapi31.pyis not excluded, and is black-clean.Adjacent and deliberately left out of scope: on the 3.0 side,
json.dumps(schema['properties'], ...)is still unguarded, so a non-object request body raisesKeyError: 'properties'. The 3.1 side got a guard for that in cca8fc3, which was not ported across. Different bug, and this PR is one line per file — happy to file it separately if that's useful.