sphinx-contrib / sphinx-contrib/openapi

`sphinx-build -W` raises an exception

Open
#115 0 comments 1 reaction 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

Hi there,

because our team would like to validate the correctness of Sphinx-syntax in our docstrings, we intend to use the -W parameter of sphinx-build. Unfortunately, this also converts this warning into an exception:

Traceback (most recent call last):
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/cmd/build.py", line 280, in build_main
    app.build(args.force_all, filenames)
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/application.py", line 337, in build
    self.builder.build_all()
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 257, in build_all
    self.build(None, summary=__('all source files'), method='all')
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 307, in build
    updated_docnames = set(self.read())
  File "/usr/lib/python3.8/contextlib.py", line 120, in __exit__
    next(self.gen)
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/util/logging.py", line 213, in pending_warnings
    memhandler.flushTo(logger)
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/util/logging.py", line 178, in flushTo
    logger.handle(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 1599, in handle
    self.callHandlers(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 1661, in callHandlers
    hdlr.handle(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 950, in handle
    rv = self.filter(record)
  File "/usr/lib/python3.8/logging/__init__.py", line 811, in filter
    result = f.filter(record)
  File "/home/andi/virtualenvs/smelt/lib/python3.8/site-packages/sphinx/util/logging.py", line 423, in filter
    raise exc
sphinx.errors.SphinxWarning: <openapi>:1:Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.

Warning, treated as error:
<openapi>:1:Problem in http domain: field is supposed to use role 'obj', but that role is not in the domain.
Versions
Sphinx                         4.1.2
sphinxcontrib-httpdomain       1.7.0
sphinxcontrib-openapi          0.7.0
Steps to Reproduce

In one of the documents I have added the openapi directive:

.. openapi:: ./openapi_trunc.yml

The contents of the schema look like this (truncated, but still causing the warning):

openapi: 3.0.2
info:
  title: 'SMELT'
  version: 'v1'
paths:
  /reports/maintenance/monthly_group_{group_name}/:
    get:
      operationId: retrieveMonthlyReportGroup
      description: Add links to all reports to context
      parameters:
      - name: group_name
        in: path
        required: true
        description: ''
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema: {}
          description: ''
      tags:
      - reports

Build command: sphinx-build -W -a -T -b html source/ /tmp/html/

Expected behavior

Unfortunately, I'm not familiar with the Sphinx internals, but my guess: If the role does not exist, it should not be used.

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 by reproducing the issue with the openapi directive and sphinx-build -W -a -T -b html source/ /tmp/html/ using the versions listed. Trace how the OpenAPI extension handles the HTTP-domain field role, then verify that a valid schema builds with -W without raising the reported warning as an exception.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, python
Domain
api, documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.