[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Change by Meer Suri :


--
pull_requests: +29564
pull_request: https://github.com/python/cpython/pull/31429

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Meer Suri  added the comment:

https://docs.python.org/3.11/library/io.html?highlight=io#text-i-o -

The easiest way to create a text stream is with open(), optionally specifying 
an encoding:

https://docs.python.org/3.11/library/io.html?highlight=io#binary-i-o - 

The easiest way to create a binary stream is with open() with 'b' in the mode 
string:

For both of these cases, the markup for the open() is :meth:`open()` but it 
links to the builtins open(), which I see is an alias of io.open() so maybe it 
doesn't matter?
Another question is why do only these two instances use :meth: while the other 
instances in the file use :func: (some refer directly to builtins open() so its 
understandable, but not all instances)
I'm wondering if the above two should be left alone or changed to 
:meth:`~io.open` or even :func:`open`

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Meer Suri  added the comment:

Looks like another one - 
https://docs.python.org/3.11/library/fileinput.html#fileinput.hook_encoded

Deprecated since version 3.10: This function is deprecated since input() and 
FileInput now have encoding and errors parameters.

The input() here points to builtins which doesnt have the mentioned parameters

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Meer Suri  added the comment:

Also this one?- 

https://docs.python.org/3.11/library/urllib.request.html?highlight=urllib%20request#urllib.request.OpenerDirector.open

Arguments, return values and exceptions raised are the same as those of 
urlopen() (which simply calls the open() method on the currently installed 
global OpenerDirector).

open() points to the builtins function but the markup used is :meth:`open` and 
the logic of the sentence suggests the link was meant to be to 
OpenerDirector.open()

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Meer Suri  added the comment:

Thanks Jelle for the cool idea of the script to look for more instances of this 
problem. I've been working on this script and am still refining it, but one of 
the candidates that my program returned is in zipfile.rst - 
https://docs.python.org/3.11/library/zipfile.html?highlight=zipfile#zipfile.ZipFile.open
 

Changed in version 3.6: open() can now be used to write files into the archive 
with the mode='w' option.
Changed in version 3.6: Calling open() on a closed ZipFile will raise a 
ValueError. Previously, a RuntimeError was raised.

Here the first instance of open() points to the builtins function rather than 
ZipFile.open(), whereas the second instance points to ZipFile.open(). Seems 
like a true positive to me, what do you think?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Ethan Furman]

Ethan Furman  added the comment:


New changeset 9d9cfd61ec3cbe84dbc25c74f664877f3d02b8ef by Meer Suri in branch 
'main':
bpo-46586: Fix documentation links (GH-31216)
https://github.com/python/cpython/commit/9d9cfd61ec3cbe84dbc25c74f664877f3d02b8ef


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Éric Araujo]

Éric Araujo  added the comment:

Thinking about it again: The issue is that these tables (for sys.float_info and 
other named tuples / structseqs) use the const role, which is not meant to 
identify attributes but to link to them (similar to func, mod, data, etc).  In 
other words we are fixing an issue that a wrong target is used, but we should 
not be linking for a target at all, this is the target.  So if we can’t use the 
equivalent of directives function, module, etc (that define the targets of 
func, mod, etc), then maybe they should be just ``name``, not :role:`name`.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Zachary Ware]

Zachary Ware  added the comment:

An updated reST linting check was added between the time you created the PR and 
your last update.  As Jelle noted on the PR, there doesn't need to be a NEWS 
entry for this anyway.

We might have an issue there if sphinx-lint is going to have an issue with no 
trailing newline and blurb-it isn't going to add a trailing newline, though. 
(+mdk)

--
nosy: +mdk, zach.ware

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Meer Suri  added the comment:

Can someone guide me on why I'm getting a no-new-line at end of file error for 
the NEWS entry when I didnt change this file in the last commit and it passed 
the Azure checks earlier

Error: [1] 
../Misc/NEWS.d/next/Documentation/2022-02-08-15-38-16.bpo-46586.6qVFVL.rst:0: 
No newline at end of file (no-newline-at-end-of-file). Do I need to manually 
add the new line?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Jelle Zijlstra]

Jelle Zijlstra  added the comment:

> How do I find other instances of this problem? Is there a systematic way to 
> look for such references?

You could write a script that goes something like this, iterating over all the 
docs RST files:

- Find all definitions in the file (e.g. `.. decorator:: property`)
- Filter to those that have names that also appear in builtins
- Find any links using those names within the same file

That would catch the enum.property case, but not the float_info one Éric 
noticed, because sys.rst doesn't define `max` at all. To catch that one, you 
could look at the link role: sys.rst links to it with :const:`max`, but 
functions.rst defines it as `.. function:: max`. Mismatches like that could be 
another clue that something is wrong (but there are some legitimate reasons why 
the roles won't match perfectly, like "decorator" in the definition vs. "func" 
in the link).

--
nosy: +Jelle Zijlstra

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Meer Suri  added the comment:

It took me some time to figure out how to prevent the creation of a 
reference/hyperlink using the ! prefix. I've made the change to remove the 
references to the max and min attributes of sys.float_info and pushed.

How do I find other instances of this problem? Is there a systematic way to 
look for such references?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Éric Araujo]

Éric Araujo  added the comment:

Yes, I was referring to these two attributes.
They should not link to anything: the place I linked *is* the documentation for 
them.
Other instances of this problem could be listed in this ticket and fixed by the 
same PR (doesn’t matter than enum.property is only for 3.11, the backport PRs 
can be a little different), or tracked in a separate ticket if that seems more 
convenient.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Meer Suri  added the comment:

I looked through the sys.float_info docs and I guess that you are referring to 
the max and min attributes of sys.float_info that are linking to the built-in 
max() and min() functions?

In that case as there is no documentation for the max and min attributes of 
sys.float_info, should they not link to anything?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Éric Araujo]

Éric Araujo  added the comment:

The same problem exists for any attribute that has the same name as a builtin, 
see for example https://docs.python.org/3/library/sys.html#sys.float_info

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Roundup Robot]

Change by Roundup Robot :


--
keywords: +patch
nosy: +python-dev
nosy_count: 6.0 -> 7.0
pull_requests: +29386
stage: needs patch -> patch review
pull_request: https://github.com/python/cpython/pull/31216

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Éric Araujo]

Éric Araujo  added the comment:

Using a substitution is necessary when we need code markup and a link.

For this bug, the simple ~ markup will be enough.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Meer Suri]

Meer Suri  added the comment:

(First time contributor here seeking guidance) I see that this problem of 
automatically linking to the unintended page has occurred in other parts of the 
docs and has been handled in another way - In Doc/library/functions.rst, local 
targets are used with replacement texts-

unintended linking code- :func:`dict`
local target code- |func-dict|_ 
and this substitution is added-  .. |func-dict| replace:: ``dict()``

Would this be the preferred way of solving this? I tried this change and it 
achieves the correct linking for me

--
nosy: +meersuri

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Ethan Furman]

Change by Ethan Furman :


--
Removed message: https://bugs.python.org/msg412634

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Ethan Furman]

Ethan Furman  added the comment:

In case a future reader has the same question:

A tilde (~) creates a link to whatever follows (so `enum.property` above), but 
only shows the last segment in the text (so `property`).

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Alex Waygood]

Alex Waygood  added the comment:

The ~ always only uses the final part of the name for the display text, e.g.  
`~collections.abc.Iterator` would have "Iterator" as the visible text on the 
website.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Alex Waygood]

Alex Waygood  added the comment:

:func:`~enum.property` means that the visible text on the webpage will be 
"property", but the link will be to enum.property rather than builtins.property.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Ethan Furman]

Ethan Furman  added the comment:

What does the tilde (~) do?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Alex Waygood]

Alex Waygood  added the comment:

`enum.property` is new in Python 3.11, so this isn't an issue for 3.9 or 3.10.

--
nosy: +AlexWaygood
versions:  -Python 3.10, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Éric Araujo]

Éric Araujo  added the comment:

Changing the markup to this should fix the link without changing the text:

   :func:`~enum.property`

Would you like to turn this into a pull request?

--
keywords: +easy
nosy: +eric.araujo
versions: +Python 3.10, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Alex Waygood]

Change by Alex Waygood :


--
assignee: docs@python -> ethan.furman
nosy: +ethan.furman
stage:  -> needs patch
type:  -> behavior

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue46586] In documentation contents enum.property erroneously links to built-in property

[Dutcho]

New submission from Dutcho :

https://docs.python.org/3.11/library/enum.html#module-contents contains:
property()
Allows Enum members to have attributes without conflicting with member names.

In above, property() is links to:
https://docs.python.org/3.11/library/functions.html#property
instead of to the proper:
https://docs.python.org/3.11/library/enum.html#enum.property

--
assignee: docs@python
components: Documentation
messages: 412156
nosy: Dutcho, docs@python
priority: normal
severity: normal
status: open
title: In documentation contents enum.property erroneously links to built-in 
property
versions: Python 3.11

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com