Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

autodoc_typehints='signature' doesn't handle None #7428

godlygeek opened this issue Apr 6, 2020 · 3 comments

autodoc_typehints='signature' doesn't handle None #7428

godlygeek opened this issue Apr 6, 2020 · 3 comments


Copy link

Describe the bug
Given a Python file containing:

def foo() -> None: pass

And a containing:

extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]
intersphinx_mapping = {"python": ("", None)}

The latest Sphinx installed from PyPI generates:

.. py:function:: foo() -> None
   :module: type_hint_test

And then winds up generating a warning, if -n is enabled: of
WARNING: py:class reference target not found: None

Which of course fails the build if -W is enabled.

This works fine if the return type is int instead of None - I'm guessing that the issue is the type is resolved using py:class, but that None is special, as per PEP-484:

When used in a type hint, the expression None is considered equivalent to type(None).

To Reproduce

mkdir -p sphinx_type_hint_none
cd sphinx_type_hint_none

printf "%s\n" > \
    "def foo() -> None: pass"     \

mkdir -p docs

printf "%s\n" > docs/                                                \
    'extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]'         \
    'intersphinx_mapping = {"python": ("", None)}' \

printf "%s\n" > docs/index.rst       \
    '.. automodule:: type_hint_test' \
    '.. autofunction:: foo'          \

mkdir -p html
python3.8 -m sphinx -vvv -nW -b html --keep-going docs html

Expected behavior
Documentation generation completes without an error, and includes a link to

Environment info

  • OS: Linux 4.4.0
  • Python version: 3.8.1
  • Sphinx version: 3.0.0
  • Sphinx extensions: sphinx.ext.autodoc, sphinx.ext.intersphinx

Additional context
Appears to have been introduced in 3.0.0; our CI had no issue with the latest version on PyPI as of Friday.

@tk0miya tk0miya added this to the 3.0.1 milestone Apr 7, 2020
Copy link

tk0miya commented Apr 7, 2020

+1; Reasonable.
I worked to suppress warnings for built-in types in 3.0 (see #6895). But I forgot to handle None.

Copy link
Contributor Author

godlygeek commented Apr 7, 2020

Note that if I use autodoc_typehints='description', the generated HTML contains:

<dt class="field-even">Return type</dt>
<dd class="field-even"><p><a class="reference external" href="" title="(in Python v3.8)">None</a></p>

That is, it generates a clickable link to the None singleton from the Return type section. It seems inconsistent for autodoc_typehints='description' to generate a link to the None singleton's documentation but for autodoc_typehints='signature' to not generate a link.

tk0miya added a commit that referenced this issue Apr 8, 2020
Fix #7428: py domain: a reference to class ``None`` emits a nitpicky warning
Copy link

tk0miya commented Apr 8, 2020

Fixed by #7432
Thank you for reporting.

@godlygeek I think it is another topic. So please file another issue. Thanks,

@tk0miya tk0miya closed this as completed Apr 8, 2020
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 26, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
None yet

No branches or pull requests

2 participants