FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

gh-101100: Fix sphinx warnings in `howto/*` · Pull Request #127084 · python/cpython · GitHub

Repository navigation

gh-101100: Fix sphinx warnings in howto/* - #127084

Merged
hugovk merged 4 commits into
mainfrom
unknown repository
Nov 26, 2024
Merged

hugovk merged 4 commits into
mainfrom
unknown repository

Conversation

ghost commented Nov 21, 2024 •
edited by github-actions Bot
Loading

Copy link
Copy Markdown

Removed sphinx roles of some classes and methods, as the classes are defined in the sample codes, not in Python.

Fixed warnings:

howto/descriptor.rst:45: WARNING: py:class reference target not found: Ten [ref.class]
howto/descriptor.rst:218: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:218: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:256: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:340: WARNING: py:class reference target not found: Validator [ref.class]
howto/descriptor.rst:363: WARNING: py:class reference target not found: Validator [ref.class]
howto/descriptor.rst:363: WARNING: py:meth reference target not found: validate [ref.meth]
howto/descriptor.rst:372: WARNING: py:class reference target not found: OneOf [ref.class]
howto/descriptor.rst:374: WARNING: py:class reference target not found: Number [ref.class]
howto/descriptor.rst:378: WARNING: py:class reference target not found: String [ref.class]
howto/descriptor.rst:876: WARNING: py:class reference target not found: Field [ref.class]
howto/descriptor.rst:1143: WARNING: py:func reference target not found: Property [ref.func]
howto/enum.rst:78: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:90: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:113: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:131: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:576: WARNING: py:class reference target not found: Animal [ref.class]
howto/enum.rst:893: WARNING: py:class reference target not found: FloatEnum [ref.class]

📚 Documentation preview 📚: https://cpython-previews--127084.org.readthedocs.build/

Removed sphinx roles of some classes and methods,
as the classes are defined in the sample codes, not in Python.

Fixed warnings:
```
howto/descriptor.rst:45: WARNING: py:class reference target not found: Ten [ref.class]
howto/descriptor.rst:218: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:218: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:256: WARNING: py:class reference target not found: Person [ref.class]
howto/descriptor.rst:340: WARNING: py:class reference target not found: Validator [ref.class]
howto/descriptor.rst:363: WARNING: py:class reference target not found: Validator [ref.class]
howto/descriptor.rst:363: WARNING: py:meth reference target not found: validate [ref.meth]
howto/descriptor.rst:372: WARNING: py:class reference target not found: OneOf [ref.class]
howto/descriptor.rst:374: WARNING: py:class reference target not found: Number [ref.class]
howto/descriptor.rst:378: WARNING: py:class reference target not found: String [ref.class]
howto/descriptor.rst:876: WARNING: py:class reference target not found: Field [ref.class]
howto/descriptor.rst:1143: WARNING: py:func reference target not found: Property [ref.func]
howto/descriptor.rst:1725: WARNING: py:class reference target not found: Object [ref.class]
howto/enum.rst:78: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:90: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:113: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:131: WARNING: py:class reference target not found: Weekday [ref.class]
howto/enum.rst:576: WARNING: py:class reference target not found: Animal [ref.class]
howto/enum.rst:893: WARNING: py:class reference target not found: FloatEnum [ref.class]
```
hugovk added needs backport to 3.12 only security fixes needs backport to 3.13 only security fixes labels Nov 24, 2024
Comment thread Doc/howto/descriptor.rst Outdated
----------------------------------------------------

The :class:`Ten` class is a descriptor whose :meth:`__get__` method always
The ``Ten`` class is a descriptor whose :meth:`__get__` method always

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

If we keep the class role but add an exclamation mark then we keep the formatting of a class but don't try to resolve the reference, and get no warning:

Suggested change
The ``Ten`` class is a descriptor whose :meth:`__get__` method always
The :class:`!Ten` class is a descriptor whose :meth:`!__get__` method always

Re: https://devguide.python.org/documentation/markup/#roles

Same applies to the others in this PR.

And we can also do it for the example __get__ method here.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

@hugovk Fixed class references by using ! prefix. __get__ is documented in https://docs.python.org/3/reference/datamodel.html#object.__get__ , so I think it is better to fix __get__ to ~object.__get__.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

__get__ is documented in docs.python.org/3/reference/datamodel.html#object.get , so I think it is better to fix __get__ to ~object.__get__.

Yes, good idea.

ghost changed the title gh-101100: Remove roles of sample classes in howto/* gh-101100: Fix sphinx warnings in howto/* Nov 25, 2024
ghost requested a review from hugovk November 25, 2024 11:34

hugovk left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason Spam Abuse Off Topic Outdated Duplicate Resolved Low Quality

Thanks!

hugovk merged commit 733fe59 into python:main Nov 26, 2024

Copy link
Copy Markdown

Thanks @koyuki7w for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12, 3.13.
🐍🍒⛏🤖

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Nov 26, 2024
(cherry picked from commit 733fe59)

Co-authored-by: Yuki Kobayashi <drsuaimqjgar@gmail.com>

Copy link
Copy Markdown

Sorry, @koyuki7w and @hugovk, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 733fe59206e04141fd5cf65606ebd3d42a996226 3.12

bedevere-app Bot commented Nov 26, 2024

Copy link
Copy Markdown

GH-127287 is a backport of this pull request to the 3.13 branch.

bedevere-app Bot removed the needs backport to 3.13 only security fixes label Nov 26, 2024

hugovk commented Nov 26, 2024

Copy link
Copy Markdown
Member

@koyuki7w Please could you take care of the 3.12 backport? Thanks!

hugovk pushed a commit that referenced this pull request Nov 26, 2024
Co-authored-by: Yuki Kobayashi <drsuaimqjgar@gmail.com>

bedevere-app Bot commented Nov 27, 2024

Copy link
Copy Markdown

GH-127311 is a backport of this pull request to the 3.12 branch.

bedevere-app Bot removed the needs backport to 3.12 only security fixes label Nov 27, 2024

ghost commented Nov 27, 2024

Copy link
Copy Markdown
Author

@hugovk Thanks. Opened 3.12 backport PR.

ghost deleted the doc-fix-2 branch November 27, 2024 00:58
ebonnal pushed a commit to ebonnal/cpython that referenced this pull request Jan 12, 2025
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters. Learn more about bidirectional Unicode characters
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation in the Doc dir skip news

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant


Back | FazBrowse Home | New Git URL