sphinx-contrib / openapi

OpenAPI (fka Swagger) spec renderer for Sphinx.
https://sphinxcontrib-openapi.readthedocs.io
BSD 2-Clause "Simplified" License
111 stars 80 forks source link

`sphinx-build -W` raises an exception #115

Open crazyscientist opened 3 years ago

crazyscientist commented 3 years ago

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.