bpo-45292: [PEP-654] exception groups and except* documentation

[iritkatriel]

https://bugs.python.org/issue45292

[iritkatriel]

@willingc Is there anyone from the documentation experts who may be interested in helping with this?

[gvanrossum]

@Fidget-Spinner Are you available to help here?

[willingc]

@iritkatriel I'm happy to help if @Fidget-Spinner is unavailable. I'm assuming you wish for some help to resolve whatever is causing the doc build to error.

[willingc]

Irit, this looks good. Looking into the keyword errors.

[iritkatriel]

@iritkatriel I'm happy to help if @Fidget-Spinner is unavailable. I'm assuming you wish for some help to resolve whatever is causing the doc build to error.

Thank you. Not just the formatting error, also a fresh reader who can see if it’s clear and consistent with the documentation style, and whether things are where they belong and at the right level of detail.

[willingc]

@iritkatriel I think the tone and content are well done. I need to drop for the evening but feel free to merge if the build error resolves. Ping me in the morning if you get stuck on that. Thanks!

[Fidget-Spinner]

Hi @iritkatriel, you need to create a label/anchor (I forgot the term) for except_star. See line 221-223 of compound_stmts.rst for an example. Adding a .._except_star: under the try, except, finally labels should be sufficient.

For some reason, keyword labels must be placed preceding a title, even though rST supports arbitrary anchors normally. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref for more info.

[iritkatriel]

Thank you @willingc and @Fidget-Spinner , it's looking good now.

I will give @gvanrossum and @1st1 and anyone else a chance to review before merging. There isn't any rush with this - the early users we have now already read the PEP.

[Fidget-Spinner]

Wow! This is the first time I'm reading about PEP 654 in more detail, and I did not realize it was this powerful!

Speaking from the perspective of a newbie, I understood what you wrote. The tutorial and language reference is very clear to me.

[Zac-HD]

I'm happy to take comments related to .__note__ over on my PEP 678 draft 😁

[iritkatriel]

Shall I merge this? It might be nice to have the documentation there when except* is released in the next alpha.

[willingc]

@iritkatriel Prior to merging, can you recap any outstanding next actions needed in a message here. Thanks!

[iritkatriel]

I believe this PR now describes the way exception groups and except* work, and is consistent with PEP654.

The new __note__ field on exception is the subject of PEP678, which is still in draft stage. The doc here describes the current implementation, which is consistent with the PEP. Any changes/reversion following the PEP678 discussions will be made in the code and the doc at the same time.

[iritkatriel]

I could also split out the __note__ section into a separate PR and merge only the PEP654 stuff for now if that works better.

[gvanrossum]

I could also split out the __note__ section into a separate PR and merge only the PEP654 stuff for now if that works better.

Yeah, let's keep __note__ undocumented until its PEP has been approved.

[iritkatriel]

Thank you everyone!

The notes section is in this draft PR #30441.