Skip to content

Some of the new httpdomain options fail with "unknown option" error #165

@stativ

Description

@stativ

When I try to change the response-examples-for option for the new httpdomain renderer, sphinx-build always prints the following error and no examples are generated:

/home/stativ/development/workdir/astra-open-api/index.rst:29: ERROR: Error in "openapi" directive:
unknown option: "response-examples-for".

The same problem happens with the other options that have :None in the option_spec, too.

This happens with the latest sphinx-openapi commit e2c4473 and sphinx 8.2.3

I was able to get it working with this change, but I have no idea whether that is a correct fix:

--- /tmp/openapi/sphinxcontrib/openapi/renderers/_httpdomain.py 2025-05-28 15:25:48.991128250 +0200
+++ .venv/lib/python3.13/site-packages/sphinxcontrib/openapi/renderers/_httpdomain.py   2025-05-28 17:09:13.354386574 +0200
@@ -196,7 +198,7 @@
     option_spec = {
         "markup": functools.partial(directives.choice, values=_markup_converters),
         "http-methods-order": lambda s: s.split(),
-        "response-examples-for": None,
+        "response-examples-for": lambda s: set(s.split()),
         "request-parameters-order": None,
         "example-preference": None,
         "request-example-preference": None,

Now I can configure the examples as:

:response-examples-for: 200 201 202 2XX 400 401 403 404 409 423

A similar change is probably required for other options.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions