sphinx-doc / sphinx-doc/sphinx

autosummary generation considers `NewType` instances to be data, but autodoc considers them a class

Open
#11,552 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

extensions:autodoc extensions:autosummary type:bug
Dominant language
Python
Stars
8k
Forks
2.6k
PR merge metrics
No merged PRs in 30d

Description

Describe the bug

PR #10700 (addressing #10480) updates autodoc to consider NewType instances to be classes. Within autosummary templates, NewType values are listed in the attributes template parameter, not classes.

Within the rendering of a NewType stub template, the objtype is still data. autosummary documentation suggests that the objtype might be newtypedata, but "newtypedata" does not appear to occur anywhere in the code.

When autodoc generate a function that has a parameter which is a NewType instance, the parameter is annotated with a :py:class: reference, which fails to connect to the autodata entry that was used to generate the NewType stub.

How to Reproduce

Minimal repro: repro.tar.gz

To repro:

$ tar xvf repro.tar.gz
$ cd repro/
$ make

Example output:

$ make                                                                                                                                     23:33:08
sphinx-build . out/ -Wn
Running Sphinx v7.1.2
[autosummary] generating autosummary for: generated/repro.func.rst, generated/repro.rst, index.rst
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 3 source files that are out of date
updating environment: [new config] 3 added, 0 changed, 0 removed
reading sources... [100%] index
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [100%] index

Warning, treated as error:
.../repro/repro.py:docstring of repro.func:1:py:class reference target not found: repro.NewInt
Makefile:2: recipe for target 'reproduce-error' failed
make: *** [reproduce-error] Error 2

File Contents:

index.rst:

Test
####

.. autosummary::
    :toctree: generated
    :template: module.t.rst

    repro

repro.py:

"""Module"""
import typing

NewInt = typing.NewType("NewInt", int)


def func(v: NewInt) -> None:
    "hey"
    ...

conf.py

import pathlib
import sys

templates_path = ["."]
exclude_patterns = ["*.t.rst"]
sys.path.append(str(pathlib.Path(__file__).parent.resolve()))
extensions = [
    "sphinx.ext.autosummary",
    "sphinx.ext.autodoc",
]

module.t.rst

{{ fullname | escape | underline }}

.. automodule:: {{ fullname }}

  {% if attributes -%}
  .. rubric:: Data
  .. autosummary::
    :toctree:

    {% for data in attributes -%}
    {{ data }}
    {%- endfor %}
  {% endif %}

  {% if functions -%}
  .. rubric:: Functions
  .. autosummary::
    :toctree:

    {% for fn in functions -%}
    {{ fn }}
    {% endfor %}
  {% endif %}

  {% if classes -%}
  .. rubric:: Classes & Types
  .. autosummary::
    :toctree:

    {% for cls in classes -%}
    {{ cls }}
    {% endfor %}
  {% endif %}

Makefile

reproduce-error:
	sphinx-build . out/ -Wn
Environment Information
Please paste all output below into the bug report template



Platform:              linux; (Linux-4.15.0-161-generic-x86_64-with-glibc2.27)
Python version:        3.10.1 (main, Jan 13 2022, 19:20:57) [GCC 7.5.0])
Python implementation: CPython
Sphinx version:        7.1.2
Docutils version:      0.20.1
Jinja2 version:        3.1.2
Pygments version:      2.15.1
Sphinx extensions
sphinx.ext.autodoc
sphinx.ext.autosummary
Additional context

No response

Contributor guide

Open the contributing guide

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 unpacking repro.tar.gz and running make to reproduce the missing repro.NewInt reference. Trace how autosummary places NewType values in attributes and how autodoc classifies them, then compare the generated stub and parameter reference. Done means the NewType appears in the appropriate template category and the example builds without the reference warning.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.