[issue40994] Very confusing documenation for abc.Collections

[Cheryl Sabella]

Cheryl Sabella  added the comment:


New changeset 0694b82381ff27e10bb15172da0832a7e65aaa2d by Miss Islington (bot) 
in branch '3.8':
bpo-40994: Ungroup items in collections.abc documentation for improved clarity 
(GH-21880) (#21927)
https://github.com/python/cpython/commit/0694b82381ff27e10bb15172da0832a7e65aaa2d


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Cheryl Sabella]

Cheryl Sabella  added the comment:


New changeset f497bbeed08e5a7f83adecf330b61fb88e9c3fa6 by Miss Islington (bot) 
in branch '3.9':
bpo-40994: Ungroup items in collections.abc documentation for improved clarity 
(GH-21880) (#21926)
https://github.com/python/cpython/commit/f497bbeed08e5a7f83adecf330b61fb88e9c3fa6


--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Cheryl Sabella]

Cheryl Sabella  added the comment:

@Sydney Pemberton, thank you for the bug report and for the PR!

--
nosy: +cheryl.sabella
resolution:  -> fixed
stage: patch review -> resolved
status: open -> closed
type:  -> enhancement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[miss-islington]

Change by miss-islington :


--
pull_requests: +21039
pull_request: https://github.com/python/cpython/pull/21926

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[miss-islington]

Change by miss-islington :


--
pull_requests: +21040
pull_request: https://github.com/python/cpython/pull/21927

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[miss-islington]

miss-islington  added the comment:


New changeset 2ce39631f679e14132a54dc90ce764259d26e166 by Sydney Pemberton in 
branch 'master':
bpo-40994: Ungroup items in collections.abc documentation for improved clarity 
(GH-21880)
https://github.com/python/cpython/commit/2ce39631f679e14132a54dc90ce764259d26e166


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Irit Katriel]

Change by Irit Katriel :


--
versions: +Python 3.10, Python 3.9

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Roundup Robot]

Change by Roundup Robot :


--
keywords: +patch
nosy: +python-dev
nosy_count: 6.0 -> 7.0
pull_requests: +21004
stage:  -> patch review
pull_request: https://github.com/python/cpython/pull/21880

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Sydney Pemberton]

Sydney Pemberton  added the comment:

Yes, that would be great. I will figure out how to do that shortly.

On Fri, Aug 14, 2020 at 3:23 AM Irit Katriel  wrote:

>
> Irit Katriel  added the comment:
>
> Sydney, do you want to create a PR for this? I'm happy to if you don't.
>
> --
>
> ___
> Python tracker 
> 
> ___
>

-- 

Sydney Pemberton

Software Engineer

512.740.6591

spember...@auntbertha.com
Aunt Bertha  | The Social Care Network

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Irit Katriel]

Irit Katriel  added the comment:

Sydney, do you want to create a PR for this? I'm happy to if you don't.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Irit Katriel]

Irit Katriel  added the comment:

Looks like this is not the first time this has come up: 
https://stackoverflow.com/questions/39789876/why-collections-callable-provides-contains-hash-len-and-ca

The link directly to the #collections.abc.Callable section is what makes it 
confusing: 

https://python.readthedocs.io/en/latest/library/collections.abc.html#collections.abc.Callable

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Georg Brandl]

Georg Brandl  added the comment:

FWIW, I think Sydney's right. Shared entries should only be used for closely 
related, or interdependent, APIs, which those here are not.

--
nosy: +georg.brandl

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Sydney Pemberton]

Sydney Pemberton  added the comment:

Nothing to do with Jupyter itself.
When I'm reading the documentation I don't necessarily think that a sibling
"node" in the document structure is going to have anything to do with my
current section.
So it was weird to see the section entirely empty.

Also, I'm not saying that all non-native speakers are going to be
unfamiliar with the construction, but it is certainly more widely
understandable if the definitions are kept separate.

On Thu, Aug 13, 2020 at 12:54 PM Irit Katriel 
wrote:

>
> Irit Katriel  added the comment:
>
> Sydney, is the issue related to how Jupyter notebook displays the
> documentation?
>
> --
>
> ___
> Python tracker 
> 
> ___
>

-- 

Sydney Pemberton

Software Engineer

512.740.6591

spember...@auntbertha.com
Aunt Bertha  | The Social Care Network

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Irit Katriel]

Irit Katriel  added the comment:

Sydney, is the issue related to how Jupyter notebook displays the documentation?

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[శ్రీనివాస్ రెడ్డి తాటిపర్తి]

Srinivas  Reddy Thatiparthy(శ్రీనివాస్ రెడ్డి తాటిపర్తి) 
 added the comment:

English is my second language and I am familiar with the expression 
“respectively” since it is used very often in high school mathematics.

--
nosy: +thatiparthy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Sydney Pemberton]

Sydney Pemberton  added the comment:

If you look at the Jupyter notebook it should be fairly clear but to
summarize here is the issue:

class collections.abc.Container
class collections.abc.Hashable
class collections.abc.Sized
class collections.abc.Callable
ABCs for classes that provide respectively the
methods __contains__(), __hash__(), __len__(), and __call__().

This should become

class collections.abc.Container
ABC for classes that provide the method __contains__().
class collections.abc.Hashable
 ABC for classes that provide the method __hash__().
class collections.abc.Sized
ABC for classes that provide the method __len()__.
class collections.abc.Callable
ABC for classes that provide the method __call__().

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Irit Katriel]

Irit Katriel  added the comment:

Can you be more specific about what you found confusing? What is the 
documentation bug? What do you mean by "this point in the documentation"?

Even better, can you suggest how to rewrite the documentation to make it 
clearer?

--
nosy: +iritkatriel

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Karthikeyan Singaravelan]

Change by Karthikeyan Singaravelan :


--
nosy: +rhettinger

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue40994] Very confusing documenation for abc.Collections

[Sydney Pemberton]

New submission from Sydney Pemberton :

I was writing a Jupyter notebook at the time, which I think perfectly 
illustrated the blind alley this documentation bug led me down before beating 
me up and stealing my lunch money.

I have come to this point in the documentation at least half a dozen times 
while learning Python and always left confused and with the sense that Python 
is more complicated than I had thought. 

Notebook attached. 

This documentation style violates two principles:
 - The implied structure of headings and content below it.
 - Many natural languages do not contain context-sensitive grammar and so using 
the "respectively" idiom can be very confusing for people who speak English as 
a second language.

--
assignee: docs@python
components: Documentation
files: Confusing docs.ipynb
messages: 371690
nosy: Sydney Pemberton, docs@python
priority: normal
severity: normal
status: open
title: Very confusing documenation for abc.Collections
versions: Python 3.8
Added file: https://bugs.python.org/file49238/Confusing docs.ipynb

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com