classification
Title: Collections ABCs can’t be linked to
Type: Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2, Python 3.3, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: docs@python, eric.araujo, ezio.melotti, georg.brandl, python-dev, rhettinger, sandro.tosi
Priority: normal Keywords: patch

Created on 2010-12-03 18:06 by eric.araujo, last changed 2011-03-28 18:40 by eric.araujo. This issue is now closed.

Files
File name Uploaded Description Edit
issue10617.diff ezio.melotti, 2011-03-21 05:21 Patch against 2.7 review
issue10617-2.diff ezio.melotti, 2011-03-25 17:54 Patch against 2.7 w/ list under the table review
10617-2.png ezio.melotti, 2011-03-25 18:11 Screenshot of the rendered doc
Messages (19)
msg123277 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-03 18:06
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.
msg130372 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2011-03-08 20:46
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 :)
msg130397 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-09 02:10
Doc moved: correct.

Changing roles to directives: yes, that’s what I meant.
msg130457 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2011-03-09 19:08
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 :)
msg130466 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-09 21:20
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.
msg130911 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-03-14 21:40
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;
msg130916 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-03-14 21:57
Georg, do you have a recommendation?
msg131548 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-03-20 21:45
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.
msg131614 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-03-21 05:21
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__.)
msg131616 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2011-03-21 06:58
This looks fine, but it may be better to put the tables first and details second.
msg131618 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-03-21 07:52
Yes; then the table entries will link to the descriptions below.
msg131619 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-03-21 07:53
BTW: :meth:`x <x>` should not do anything different from :meth:`x`.
msg131621 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-03-21 08:23
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 ().
msg131640 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-21 12:31
> 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.
msg132128 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-03-25 17:54
I put the list under the table and grouped a few more ABCs. If this patch is OK I'll commit it.
msg132131 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-25 18:22
What about making the class names in the table not links?
msg132391 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-03-28 10:46
New changeset cc04b591d768 by Ezio Melotti in branch '2.7':
#10617: add class directives to collections ABCs.
http://hg.python.org/cpython/rev/cc04b591d768
msg132406 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-03-28 16:27
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
msg132412 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-03-28 18:40
Thanks Ezio.
History
Date User Action Args
2011-03-28 18:40:44eric.araujosetmessages: + msg132412
2011-03-28 16:35:20ezio.melottisetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2011-03-28 16:27:30python-devsetmessages: + msg132406
2011-03-28 10:46:38python-devsetnosy: + python-dev
messages: + msg132391
2011-03-25 18:22:17eric.araujosetmessages: + msg132131
2011-03-25 18:11:52ezio.melottisetfiles: + 10617-2.png
2011-03-25 17:54:49ezio.melottisetfiles: + issue10617-2.diff

messages: + msg132128
2011-03-21 12:31:38eric.araujosetnosy: georg.brandl, rhettinger, ezio.melotti, eric.araujo, sandro.tosi, docs@python
messages: + msg131640
2011-03-21 08:23:08ezio.melottisetnosy: georg.brandl, rhettinger, ezio.melotti, eric.araujo, sandro.tosi, docs@python
messages: + msg131621
2011-03-21 07:53:08georg.brandlsetnosy: georg.brandl, rhettinger, ezio.melotti, eric.araujo, sandro.tosi, docs@python
messages: + msg131619
2011-03-21 07:52:35georg.brandlsetnosy: georg.brandl, rhettinger, ezio.melotti, eric.araujo, sandro.tosi, docs@python
messages: + msg131618
2011-03-21 06:58:27rhettingersetnosy: georg.brandl, rhettinger, ezio.melotti, eric.araujo, sandro.tosi, docs@python
messages: + msg131616
2011-03-21 05:21:06ezio.melottisetfiles: + issue10617.diff
nosy: georg.brandl, rhettinger, ezio.melotti, eric.araujo, sandro.tosi, docs@python
messages: + msg131614

assignee: georg.brandl -> ezio.melotti
keywords: + patch
stage: needs patch -> patch review
2011-03-20 21:45:11georg.brandlsetnosy: georg.brandl, rhettinger, ezio.melotti, eric.araujo, sandro.tosi, docs@python
messages: + msg131548
2011-03-14 21:57:28rhettingersetassignee: docs@python -> georg.brandl

messages: + msg130916
nosy: + rhettinger
2011-03-14 21:40:18ezio.melottisetnosy: georg.brandl, ezio.melotti, eric.araujo, sandro.tosi, docs@python
messages: + msg130911
2011-03-09 21:23:23ezio.melottisetnosy: + ezio.melotti
2011-03-09 21:20:55eric.araujosetnosy: + georg.brandl
messages: + msg130466
2011-03-09 19:08:56sandro.tosisetnosy: eric.araujo, sandro.tosi, docs@python
messages: + msg130457
2011-03-09 02:10:52eric.araujosetnosy: eric.araujo, sandro.tosi, docs@python
messages: + msg130397
2011-03-08 20:46:58sandro.tosisetnosy: + sandro.tosi

messages: + msg130372
versions: + Python 3.3
2010-12-03 18:06:22eric.araujocreate