sphinx-doc / sphinx-doc/sphinx
autosummary generation considers `NewType` instances to be data, but autodoc considers them a class
Nobody has claimed this yet.
- 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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