This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: cookielib documentation references Cookie module, not cookielib.Cookie class
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.7, Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ajtag, cheryl.sabella, demian.brecht, docs@python, georg.brandl, python-dev, r.david.murray, serhiy.storchaka
Priority: high Keywords: patch

Created on 2014-06-20 23:28 by Ajtag, last changed 2022-04-11 14:58 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
docs_class_links-2.7.patch serhiy.storchaka, 2015-03-14 19:45 review
Messages (9)
msg221133 - (view) Author: Angus Taggart (Ajtag) Date: 2014-06-20 23:28
all the links to Cookie class in the cookielib documentation point to Cookie module.


for example:

CookieJar.set_cookie(cookie)

    Set a *Cookie*, without checking with policy to see whether or not it should be set.


cookie in the documentation links to
https://docs.python.org/2/library/cookie.html#module-Cookie

cookie in the documentation should link to
https://docs.python.org/2/library/cookielib.html#cookielib.Cookie
msg238094 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-14 18:28
Georg, this looks as a bug in Sphinx configuration. Why module takes priority on class when the role is explicitly specified? I have counted about two hundreds of similar bugs in the documentation.
msg238098 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-14 19:45
Here is a patch for 2.7 that fixes above a hundred of broken class references. But may be even more broken function references. I think it would be better to fix Sphinx rules.
msg238100 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-03-14 20:51
This happens because the role is pretty much ignored by Sphinx for linking purposes.  I remember Georg talking about the reason for this, but I forget what it was.  Perhaps it would be possible to, as you suggest, have the roll affect the priority...but it may be the case that the references don't currently retain the needed information.  Regardless, that would be an issue for the Sphinx tracker.
msg254374 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-11-09 09:02
Georg, is it possible to tune Sphinx rules?
msg254396 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2015-11-09 17:59
The rules are as they are mostly for backwards compatibility. But it is rarely a problem since there is only one object with a given name.

:class:`Cookie` within the docs for cookielib would not be able to link to Cookie.Cookie since it is not found in its scope. :class:`Cookie.Cookie` works, as does :class:`~Cookie.Cookie`.

When you use the "find-in-any-namespace" syntax, i.e. :class:`.Cookie` the type *will* be taken into account.
msg282034 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2016-11-29 19:33
Thus the only way to fix links is to specify full names? Does docs_class_links-2.7.patch look good to you?
msg282257 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-12-02 21:34
New changeset 5b40d81e8883 by Serhiy Storchaka in branch '2.7':
Issue #21818: Fixed references to classes that have names matching with module
https://hg.python.org/cpython/rev/5b40d81e8883

New changeset d64e37b9204e by Serhiy Storchaka in branch '3.5':
Issue #21818: Fixed references to classes that have names matching with module
https://hg.python.org/cpython/rev/d64e37b9204e

New changeset 62c9a89a2103 by Serhiy Storchaka in branch '3.6':
Issue #21818: Fixed references to classes that have names matching with module
https://hg.python.org/cpython/rev/62c9a89a2103

New changeset c642c597d05c by Serhiy Storchaka in branch 'default':
Issue #21818: Fixed references to classes that have names matching with module
https://hg.python.org/cpython/rev/c642c597d05c
msg301196 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-09-03 19:25
Can this issue be closed?
History
Date User Action Args
2022-04-11 14:58:05adminsetgithub: 66017
2017-09-07 12:22:16berker.peksagsetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.5, Python 3.6, Python 3.7
2017-09-03 19:25:37cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg301196
2016-12-02 21:34:54python-devsetnosy: + python-dev
messages: + msg282257
2016-11-29 19:33:12serhiy.storchakasetmessages: + msg282034
stage: patch review
2015-11-09 17:59:50georg.brandlsetmessages: + msg254396
2015-11-09 09:02:43serhiy.storchakasetmessages: + msg254374
2015-03-14 20:51:00r.david.murraysetnosy: + r.david.murray
messages: + msg238100
2015-03-14 19:45:59serhiy.storchakasetpriority: normal -> high
files: + docs_class_links-2.7.patch
messages: + msg238098

keywords: + patch
2015-03-14 18:28:20serhiy.storchakasetnosy: + georg.brandl, serhiy.storchaka
type: behavior
messages: + msg238094
2014-06-22 15:49:33demian.brechtsetnosy: + demian.brecht
2014-06-20 23:28:07Ajtagcreate