[issue10617] Collections ABCs can’t be linked to
New submission from Éric Araujo <merwok@netwok.org>: ABCs in collections.rst are marked up with a class role, not a class directive, which means that constructs using the class role do not generate a link. ---------- assignee: docs@python components: Documentation messages: 123277 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Collections ABCs can’t be linked to versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Sandro Tosi <sandro.tosi@gmail.com> added the comment: Hi Éric, after #11085, I think the part of the doc you're referring to has been moved to collections.abc.rst, is that correct? If so, can you please explain what you'd like to see? all those ":class:`Container`" converted into ".. class:: Container" in the table? That will help me provide a patch :) ---------- nosy: +sandro.tosi versions: +Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Doc moved: correct. Changing roles to directives: yes, that’s what I meant. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Sandro Tosi <sandro.tosi@gmail.com> added the comment: but that will generate "class collections.abc.Container" as text in the first column of the table: do you really like it? I don't :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I don’t either. The one thing I’d like is that :class:`collections.Set` generates a link to the table which documents the ABCs. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Apparently there's no way to change the text generated by the "class" directive, so it's not possible to use it in the table without having the "class" before the names. The alternatives are: 1) define these classes normally instead of or in addition to the table; 2) leave the doc as is and close the issue; ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Raymond Hettinger <rhettinger@users.sourceforge.net> added the comment: Georg, do you have a recommendation? ---------- assignee: docs@python -> georg.brandl nosy: +rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Georg Brandl <georg@python.org> added the comment: I would recommend to document the classes like all other classes. It may take a bit more space, but it will be a) standard and b) linkable. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Here's a patch that adds the list of classes with a minimal description before the table. I grouped a few classes to save some space. Container, Hashable, Sized, Callable could be grouped too. I also added links to the methods and to glossary terms (the `set` term is missing from the glossary though). The methods listed in the table can be turned to links too. (The :meth:`__len__ <__len__>` markup is to hide the () after the __method__.) ---------- assignee: georg.brandl -> ezio.melotti keywords: +patch stage: needs patch -> patch review Added file: http://bugs.python.org/file21318/issue10617.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: This looks fine, but it may be better to put the tables first and details second. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Georg Brandl <georg@python.org> added the comment: Yes; then the table entries will link to the descriptions below. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Georg Brandl <georg@python.org> added the comment: BTW: :meth:`x <x>` should not do anything different from :meth:`x`. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: I put the list first and table second because the table contains more details and information, whereas the list only has a short description (usually the tables provide an overview and they are followed by a more comprehensive list). I didn't include the () after the methods name because they are not in the table, they look ugly on the special __methods__() and it's clear that they are methods even without the (). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment:
I didn't include the () after the methods name because [...] they look ugly on the special __methods__() and it's clear that they are methods even without the ().
I feel that way for all functions and methods in the docs, especially given Python’s distinction between getting an object and calling it, but the current Sphinx setting is to add parenthesis, so let’s follow it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: I put the list under the table and grouped a few more ABCs. If this patch is OK I'll commit it. ---------- Added file: http://bugs.python.org/file21394/issue10617-2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: Added file: http://bugs.python.org/file21395/10617-2.png _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: What about making the class names in the table not links? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Roundup Robot <devnull@devnull> added the comment: New changeset cc04b591d768 by Ezio Melotti in branch '2.7': #10617: add class directives to collections ABCs. http://hg.python.org/cpython/rev/cc04b591d768 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Roundup Robot <devnull@devnull> added the comment: New changeset c5de208d205c by Ezio Melotti in branch '3.1': #10617: add class directives to collections ABCs. http://hg.python.org/cpython/rev/c5de208d205c New changeset 3daca2b76297 by Ezio Melotti in branch '3.2': #10617: merge with 3.1. http://hg.python.org/cpython/rev/3daca2b76297 New changeset 30a026a25167 by Ezio Melotti in branch 'default': #10617: merge with 3.2. http://hg.python.org/cpython/rev/30a026a25167 ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Thanks Ezio. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10617> _______________________________________
participants (6)
-
Ezio Melotti -
Georg Brandl
-
Raymond Hettinger
-
Roundup Robot
-
Sandro Tosi
-
Éric Araujo