classification
Title: cookielib documentation references Cookie module, not cookielib.Cookie class
Type: behavior Stage: patch review
Components: Documentation Versions: Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ajtag, 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 2016-12-02 21:34 by python-dev.

Files
File name Uploaded Description Edit
docs_class_links-2.7.patch serhiy.storchaka, 2015-03-14 19:45 review
Messages (8)
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) 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
History
Date User Action Args
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