WARNING: Parameter name 'foo' does not match any of the parameters defined in the signature: ['a', 'kwargs']

[hille721]

Not sure if this is a sphinx-immaterial issue, but at least this warning just appears when using this theme. I'm using Google Docstring Format and so the Sphinx napoleon extension.

conf.py:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "sphinx_immaterial",
    ]
html_theme = 'sphinx_immaterial'

foo.py

def a_function_with_kwargs(a: str, **kwargs) -> str:

    """Google Docstring Style.

    Args:
        a: a argument

    Keyword Args:
        foo (str): a keyword argument
        bar (str): another keyword argument

    Returns:
        a result
    """

    return a

Detailed logs:

[app] emitting event: 'env-purge-doc'(<sphinx.environment.BuildEnvironment object at 0x7faf39588b50>, 'index')
[app] emitting event: 'source-read'('index', [".. test documentation master file, created by\n   sphinx-quickstart on Tue Feb 28 10:17:
[autodoc] /home/hille/sphinx-test/docs/index.rst:9: input:
.. autofunction:: foo.a_function_with_kwargs
[autodoc] from foo import a_function_with_kwargs
[autodoc] import foo => <module 'foo' from '/home/hille/sphinx-test/docs/./../foo.py'>
[autodoc] getattr(_, 'a_function_with_kwargs')
[autodoc] => <function a_function_with_kwargs at 0x7faf38083160>
[app] emitting event: 'autodoc-before-process-signature'(<function a_function_with_kwargs at 0x7faf38083160>, False)
[app] emitting event: 'autodoc-process-signature'('function', 'foo.a_function_with_kwargs', <function a_function_with_kwargs at 0x7faf38083160>, {}, 
[app] emitting event: 'autodoc-process-docstring'('function', 'foo.a_function_with_kwargs', <function a_function_with_kwargs at 0x7faf38083160>, {}, 
[autodoc] output:

.. py:function:: a_function_with_kwargs(a: str, **kwargs) -> str
   :module: foo

   Google Docstring Style.

   :param a: a argument

   :keyword foo: a keyword argument
   :kwtype foo: str
   :keyword bar: another keyword argument
   :kwtype bar: str

   :returns: a result

[app] emitting event: 'object-description-transform'('py', 'function', <desc_content: <paragraph...><field_list...>>)
[i18n] PATCH: 'docutils.nodes.field_name' to have source and line: <field_name ids="foo.a_function_with_kwargs-parameters">Parameters</field_name>
[i18n] PATCH: 'docutils.nodes.term' to have rawsource: <term ids="foo.a_function_with_kwargs.a" paramname="a" toc_title="a"><desc_sig_n...
[i18n] PATCH: 'docutils.nodes.field_name' to have source and line: <field_name ids="foo.a_function_with_kwargs-keyword-arguments">Keyword Arguments...
[i18n] PATCH: 'docutils.nodes.term' to have rawsource: <term paramname="foo" paramtype="str"><desc_name classes="sig-name descname" xml...
[i18n] PATCH: 'docutils.nodes.term' to have rawsource: <term paramname="bar" paramtype="str"><desc_name classes="sig-name descname" xml...
[i18n] PATCH: 'docutils.nodes.field_name' to have source and line: <field_name ids="foo.a_function_with_kwargs-returns">Returns</field_name>
[app] emitting event: 'doctree-read'(<document: <comment...><section "welcome to test's documentation!"...>>,)

[app] emitting event: 'env-updated'(<sphinx.environment.BuildEnvironment object at 0x7faf39588b50>,)
/home/hille/sphinx-test/foo.py:docstring of foo.a_function_with_kwargs:1: WARNING: Parameter name 'foo' does not match any of the parameters defined in the signature: ['a', 'kwargs']
/home/hille/sphinx-test/foo.py:docstring of foo.a_function_with_kwargs:1: WARNING: Parameter name 'bar' does not match any of the parameters defined in the signature: ['a', 'kwargs']

[2bndy5]

This is because the the documented args foo and bar don't appear in the signature. It would be fine if the signature was written like so:

a_function_with_kwargs(
    a: str,
    foo: str = "",
    bar: str = "",
    **kwargs
) -> str

This warning is specific to sphinx-immaterial because this theme tries to cross-link parameter desciptions in the docstring with parameter declarations in the signature.

To disable the theme's behavior about cross-linking parameters, I think you have to disable the include_in_toc setting for python parameters:

object_description_options = [
    ("py:param", dict(include_in_toc=False)),
]

Although, this suggestion might be inaccurate.

This problem is related to the proposed solution in #112 which was never implemented/resolved.

[jbms]

I don't think include_in_toc will avoid this warning. However, you could just add a rule to sphinx to ignore this warning.

[hille721]

I don't think include_in_toc will avoid this warning. However, you could just add a rule to sphinx to ignore this warning.

Make sense. Also don't see any side effect. Thanks.

Btw, already went live with the new theme today. Thanks for this amazing project!

[2bndy5]

For other passersby, given the suppress_warnings config's doc, which warning type would this fall under?

[jbms]

I'm actually not sure what warning type it would be. It would be better if you could just specify a regular expression...

[2bndy5]

Given the debug output in OP, I would think the warning type would be app (or app.event-emitted), but that would be too generic.

It would be nice to use regex... The zephyr project uses a in-house extension to filter out warnings that can't be avoided from doxygen+breathe.

[2bndy5]

I'm closing this as a better comprehensive solution is being tracked in #112