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.

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?

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__().

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

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

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 <report@bugs.python.org>
wrote:

>
> Irit Katriel <iritkatriel@yahoo.com> added the comment:
>
> Sydney, is the issue related to how Jupyter notebook displays the
> documentation?
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue40994>
> _______________________________________
>

-- 

Sydney Pemberton

Software Engineer

512.740.6591

spemberton@auntbertha.com
Aunt Bertha <https://company.auntbertha.com/> | The Social Care Network

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

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

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

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 <report@bugs.python.org> wrote:

>
> Irit Katriel <iritkatriel@yahoo.com> added the comment:
>
> Sydney, do you want to create a PR for this? I'm happy to if you don't.
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue40994>
> _______________________________________
>

-- 

Sydney Pemberton

Software Engineer

512.740.6591

spemberton@auntbertha.com
Aunt Bertha <https://company.auntbertha.com/> | The Social Care Network

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

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

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

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