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

Class attribute in subclass inherits attribute docstring in Sphinx 5.0.1 #10538

Closed
oscarbenjamin opened this issue Jun 8, 2022 · 8 comments
Closed

Comments

@oscarbenjamin
Copy link

Describe the bug

As of Sphinx 5.0.1 the SymPy docs build gives lots of warnings like this:

docstring of sympy.polys.domains.field.Field.is_Field:14: WARNING: more than one target found for cross-reference 'is_Ring': sympy.polys.domains.domain.Domain.is_Ring, sympy.polys.domains.ring.Ring.is_Ring

Full output in CI can be seen here:
https://github.com/sympy/sympy/runs/6784391829?check_suite_focus=true

The problem seems to be that there is a class Domain which has a documented attribute is_Ring:
https://github.com/sympy/sympy/blob/a96dce8b55675a0529d9bed479e2569126e27149/sympy/polys/domains/domain.py#L245-L262
You can see that in the docs here:
https://docs.sympy.org/dev/modules/polys/domainsref.html#sympy.polys.domains.domain.Domain.is_Ring

Then there is a class Ring which is a subclass of Domain and changes the value of the class attribute but does not document it:
https://github.com/sympy/sympy/blob/a96dce8b55675a0529d9bed479e2569126e27149/sympy/polys/domains/ring.py#L13

In previous versions of Sphinx the Ring class would not show the is_Ring attribute:
https://docs.sympy.org/dev/modules/polys/domainsref.html#sympy.polys.domains.ring.Ring

Now with Sphinx 5.0.1 though it seems that the Sphinx build decides to document the Ring.is_Ring attribute with the docstring inherited from the superclass Domain. Then the see also references to is_Ring fail due to multiple targets.

How to Reproduce

$ git clone https://github.com/sympy/sympy.git
$ cd sympy/doc
$ pip install -r requirements.txt
$ make html
$ # open _build/html/modules/polys/domainsref.html

Expected behavior

The attribute is_Ring in the subclass Ring would not be documented and there would be only one target for is_Ring pointing to the Domain.is_Ring attribute.

Your project

https://github.com/sympy/sympy

Screenshots

No response

OS

Any

Python version

3.8-3.10

Sphinx version

5.0.1

Sphinx extensions

Sphinx 5.0.1 sphinx-autobuild 2021.3.14 sphinx-basic-ng 0.0.1a11 sphinx-copybutton 0.5.0 sphinx-math-dollar 1.2.1 sphinx-press-theme 0.8.0 sphinx-reredirects 0.0.1 sphinxcontrib-applehelp 1.0.2 sphinxcontrib-devhelp 1.0.2 sphinxcontrib-htmlhelp 2.0.0 sphinxcontrib-jsmath 1.0.1 sphinxcontrib-qthelp 1.0.3 sphinxcontrib-serializinghtml 1.1.5

Extra tools

No response

Additional context

No response

@oscarbenjamin
Copy link
Author

Actually it seems that this is maybe caused by an update to myst-parser 0.18.0:
sympy/sympy#23598

I'm not sure where the bug is here so maybe it's not actually in Shpinx...

@oscarbenjamin
Copy link
Author

I've opened an issue with myst-parser:
executablebooks/MyST-Parser#583

I'm not sure if this is actually a bug in myst-parser rather than sphinx but I can confirm that actually it is the update to myst-parser 0.18.0 that has triggered the problem.

@oscarbenjamin
Copy link
Author

Oh, I see. Changing the myst-parser version changes the Sphinx version as well. I've confirmed that forcing sphinx to be 5.0.1 while keeping myst-parser at 0.17.2 still reproduces the problem so it's definitely a Sphinx problem.

@AA-Turner
Copy link
Member

Does it reproduce on 5.0.0 or 4.5.x? If it's a regression between 5.0.0 and 5.0.1 that's a much smaller set of changes to look for the problem in!

A

@oscarbenjamin
Copy link
Author

The problem is also present in Sphinx 5.0.0 but is not present in 4.5.0 so it seems to be a regression in between 4.5.0 and 5.0.0.

@oscarbenjamin
Copy link
Author

Bisected to efa6197 from #10447.

CC @akruis

@tk0miya
Copy link
Member

tk0miya commented Jun 13, 2022

Fixed by #10539. Thank you for reporting!

@oscarbenjamin
Copy link
Author

Thanks both!

oscarbenjamin added a commit to oscarbenjamin/sympy that referenced this issue Jun 21, 2022
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 14, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

3 participants