classification
Title: Incorrect linking to elements in datetime package
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: andymaier, docs@python, martin.panter, python-dev
Priority: normal Keywords:

Created on 2016-03-31 17:36 by andymaier, last changed 2016-04-02 23:29 by martin.panter. This issue is now closed.

Messages (10)
msg262698 - (view) Author: Andy Maier (andymaier) * Date: 2016-03-31 17:36
Hi, I did search for these in the open bugs, but did not find any matching bug.

I have a project that revealed that some of its InterSphinx links to existing classes/types or methods to not resolve their targets, or to resolve to a target that is not the right one (IMO).

This issue here describes everything I found in the datetime package.

Line numbers in this issue apply to the datetime.rst file as of commit 96a98bcaac70 (https://hg.python.org/cpython/file/96a98bcaac70/Doc/library/datetime.rst).

* class datetime.tzinfo:

  An intersphinx link to it gets resolved but targets the short description of the class in the intro (line 106 of datetime.rst), and I did not find a way to target the full description (line 1552), which is really what this should be resolved to (IMO).

  I suspect that this has to do with the fact that this class has only one anchor on its short description on line 106, while companion classes such as datetime.datetime have two anchors (lines 91 and 681) where the last one wins (and happens to be the long description). However, see the next item.

* class datetime.timezone:

  Same issue as for class datetime.tzinfo; links get resolved but land on the short intro. However, this time there are two anchors (lines 113 and 1795). So maybe my suspicion above is rather speculation...

* method datetime.tzinfo.utcoffset:

  An intersphinx link to it does not get resolved. On line 1579 in datetime.rst, there is a `.. method:: tzinfo.utcoffset(dt)` but at least these intersphinx links did not get resolved:

      :func:`py:tzinfo.utcoffset`
      :func:`py:datetime.tzinfo.utcoffset`

  Do method anchors need the anchor for their defining class close by to work? Which because if the first issue above, would be the short version of it, way above. (Again speculation)

* Same for method datetime.tzinfo.dst
msg262709 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-03-31 22:24
Currently the “datetime” documentation has quick descriptions of classes marked up with “.. class::” in the introduction, and then dedicated sections with more details. Many other parts of Python’s documentation have a similar structure.

IMO it is better to include the “.. class::” markup closer to the list of methods, and then each method can be indented underneath it. See my changes to the “socketserver” documentation (Issue 15608, compare 3.4 vs 3.5) where I indented a whole lot of methods under class definitions. I suspect the reason why things are not like this is just that it is leftover from a conversion from an earlier markup format.

The earlier class introductions are also marked up with :noindex:, which would explain which become link targets.

Dunno about your intersphinx stuff though. Is that linking to the Python documentation from external projects?
msg262729 - (view) Author: Andy Maier (andymaier) * Date: 2016-04-01 09:14
Hi Martin!

The intersphinx stuff is simply linking from a Sphinx RST documentation to a different Sphinx RST documentation, using support from the intersphinx extension of Sphinx. I think the name comes from the interwiki links in MediaWiki. It only comes into play here because my particular documentation is outside of the Python documentation. The same issues would arise when linking from other places in the Python documentation.

Your explanation about :noindex: hits the nail on the head, I think. It seems to me that a minimal variant for fixing this would be:

* add :noindex: to the class markup for the short descriptions of tzinfo and timezone.
* add a class markup for tzinfo at its long description.

I don't know whether that solves the method linking issue, though, but its worth a try.
msg262736 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-01 11:45
I’m happy to make those two minimal changes (:noindex: and tzinfo class), but I have a feeling they won’t help your problem linking to datetime.tzinfo.utcoffset() and dst(). The markup for those methods already generates index entries, see <https://docs.python.org/dev/genindex-U.html> for instance.
msg262743 - (view) Author: Andy Maier (andymaier) * Date: 2016-04-01 15:39
Ok. If these methods generate index entries, maybe the problem is on my side by not linking them correctly. So let's try with the other two changes.

Unfortunately, I cannot easily build cpython at the moment to verify, I moved to Linux and when trying to build cpython, bash rejects the configure script because of trailing CR characters. This is a freshly installed hg package on Ubuntu 14.04, against a fresh clone of the cpython repo. Any idea what is happening there?
msg262778 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-04-02 00:03
New changeset 30e077f886cc by Martin Panter in branch '3.5':
Issue #26678: Fix indexing of datetime.tzinfo and timezone classes
https://hg.python.org/cpython/rev/30e077f886cc

New changeset 854db1a2cd98 by Martin Panter in branch 'default':
Issue #26678: Merge datetime doc fixes from 3.5
https://hg.python.org/cpython/rev/854db1a2cd98

New changeset 4cad272cec82 by Martin Panter in branch '2.7':
Issue #26678: Fix datetime.tzinfo indexing and “tzinfo” attribute links
https://hg.python.org/cpython/rev/4cad272cec82
msg262779 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-02 00:24
Can you link to other methods? E.g. try io.IOBase.close(), which is done the normal way as a method indented under its class, and nntplib.NNTP.quit(), which is listed separately from its class definition. 

Regarding CRLFs in “configure”, all I can guess is some strange Mercurial user configuration. Maybe you can work around it by using the “dos2unix” command, or rebuilding the script with “autoreconf”.
msg262794 - (view) Author: Andy Maier (andymaier) * Date: 2016-04-02 11:16
Martin, I can now link to the two methods e.g. via :meth:`py:datetime.tzinfo.utcoffset`, and it resolves nicely.

See here (linking to Python 2): 
https://pywbem.readthedocs.org/en/latest/#pywbem.MinutesFromUTC

Don't know why it now works, probably user error I would say.

Your change is still appreciated, and it would be great if it could also go into Python 2.7 :-) Hope I'm not asking for too much.

On Python build: hg config problem sounds like a good path. Thanks!
msg262795 - (view) Author: Andy Maier (andymaier) * Date: 2016-04-02 11:29
Martin,
I just noticed that your fix must already be active. My link to tzinfo now lands on the long description. So maybe it was not a user error of mine that resolved the problem with the two methods (I was pretty sure I had tried the same syntax I use now), but whatever did the trick in your change.

Anyway, thanks much for this quick turnaround!!

Andy
msg262804 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-04-02 23:29
That’s good news. I did not expect it, but I seem to have fixed the problem anyway.
History
Date User Action Args
2016-04-02 23:29:15martin.pantersetstatus: open -> closed
resolution: fixed
messages: + msg262804

stage: resolved
2016-04-02 11:29:18andymaiersetmessages: + msg262795
2016-04-02 11:16:19andymaiersetmessages: + msg262794
2016-04-02 00:24:15martin.pantersetmessages: + msg262779
versions: + Python 2.7, Python 3.5
2016-04-02 00:03:30python-devsetnosy: + python-dev
messages: + msg262778
2016-04-01 15:39:33andymaiersetmessages: + msg262743
2016-04-01 11:45:09martin.pantersetmessages: + msg262736
2016-04-01 09:14:57andymaiersetmessages: + msg262729
2016-03-31 22:24:18martin.pantersetnosy: + martin.panter
messages: + msg262709
2016-03-31 17:36:39andymaiercreate