| msg123277 - (view) |
Author: Éric Araujo (eric.araujo) *  |
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) * |
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) * |
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) * |
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) * |
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) * |
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) * |
Date: 2011-03-14 21:57 |
| Georg, do you have a recommendation? |
|
|
| msg131548 - (view) |
Author: Georg Brandl (georg.brandl) * |
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) * |
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) * |
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) * |
Date: 2011-03-21 07:52 |
| Yes; then the table entries will link to the descriptions below. |
|
|
| msg131619 - (view) |
Author: Georg Brandl (georg.brandl) * |
Date: 2011-03-21 07:53 |
| BTW: :meth:`x ` should not do anything different from :meth:`x`. |
|
|
| msg131621 - (view) |
Author: Ezio Melotti (ezio.melotti) * |
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) * |
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) * |
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) * |
Date: 2011-03-25 18:22 |
| What about making the class names in the table not links? |
|
|
| msg132391 - (view) |
Author: Roundup Robot (python-dev)  |
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) |
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) * |
Date: 2011-03-28 18:40 |
| Thanks Ezio. |
|
|
