[issue26678] Incorrect linking to elements in datetime package
New submission from Andy Maier: 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 ---------- assignee: docs@python components: Documentation messages: 262698 nosy: andymaier, docs@python priority: normal severity: normal status: open title: Incorrect linking to elements in datetime package type: enhancement versions: Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Martin Panter added the comment: 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? ---------- nosy: +martin.panter _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Andy Maier added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Martin Panter added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Andy Maier added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Roundup Robot added the comment: 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 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Martin Panter added the comment: 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”. ---------- versions: +Python 2.7, Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Andy Maier added the comment: 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! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Andy Maier added the comment: 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 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
Martin Panter added the comment: That’s good news. I did not expect it, but I seem to have fixed the problem anyway. ---------- resolution: -> fixed stage: -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26678> _______________________________________
participants (3)
-
Andy Maier -
Martin Panter
-
Roundup Robot