classification
Title: Improve display of OS exception <-> errno mapping
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.4, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: brett.cannon, docs@python, eric.araujo, ezio.melotti, jon.poler, ncoghlan
Priority: normal Keywords: easy, patch

Created on 2014-07-20 07:00 by ncoghlan, last changed 2014-08-20 14:09 by brett.cannon.

Files
File name Uploaded Description Edit
OS_exceptions_table.patch jon.poler, 2014-08-13 14:49 Included OS exceptions table in Doc/library/exceptions.rst
os_exceptions_table_V2.patch jon.poler, 2014-08-17 13:53
Messages (8)
msg223499 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-07-20 07:00
It would be handy if the main OS exception docs at https://docs.python.org/3/library/exceptions.html#os-exceptions included a summary table mapping between exception types and errno names, akin to the one in the original PEP (http://www.python.org/dev/peps/pep-3151/#new-exception-classes)
msg223500 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-07-20 07:02
Another idea would be to include fragments of the ASCII art hierarchy throughout the doc, but that's trickier than it sounds, since we just use literalinclude to generate the current one.
msg224083 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-07-26 18:59
literalinclude lets you select only some lines of the file: http://sphinx-doc.org/markup/code.html#includes
msg224094 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-07-27 01:53
Oh, nice - the "start-after" and "end-before" options look like they might be the way to go.

If I'm reading the docs right, a block like the following would include the OSError section of the tree:

   .. literalinclude exceptions.txt
      :start-after: OSError
      :end-before: ReferenceError
      :prepend:

I think that's really the section that could most benefit from showing the structure inline.
msg225243 - (view) Author: Jon Poler (jon.poler) * Date: 2014-08-12 20:03
I will give this a shot if it is just hard-coding a table with errno names. Dynamically scraping the errno names and inserting them with the exception hierarchy might be beyond me since I've never used Sphinx before.
msg225264 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-08-13 07:40
I'd suggested starting with seeing including of the subsection of the exceptions.txt file looks, and if that's still a bit hard to read, try the explicit table approach.

I'm always wary of having hand maintained mappings in the docs, but this particular one isn't likely to change any time soon.
msg225282 - (view) Author: Jon Poler (jon.poler) * Date: 2014-08-13 14:49
I'm not entirely sure that I'm interpreting what you are looking for correctly, but here is what the table looks like with literalinclude.
msg225443 - (view) Author: Jon Poler (jon.poler) * Date: 2014-08-17 13:53
Here's one way to accomplish this. Please see attached os_exceptions_table_V2.patch.

I wasn't having much luck trying to use ReST, so I took advantage of the fact that the Doc/conf.py file is executed every time sphinx-build is run. conf.py imports and calls the main function from Doc/tools/build_table.py. This script dynamically builds a table by scraping errno values corresponding to an OS exception and inserting them in the appropriate place. Doc/library/exceptions.rst just uses a literalinclude of the new table that gets built to Lib/test/os_exception_hierarchy.txt (the same directory that holds the original exceptions hierarchy).

Error catching is used so that, in the event of an error, a warning will be raised but the sphinx-build command will still succeed.
History
Date User Action Args
2014-08-20 14:09:13brett.cannonsetnosy: + brett.cannon
2014-08-17 13:53:28jon.polersetfiles: + os_exceptions_table_V2.patch

messages: + msg225443
2014-08-13 14:49:51jon.polersetfiles: + OS_exceptions_table.patch
keywords: + patch
messages: + msg225282
2014-08-13 07:40:17ncoghlansetmessages: + msg225264
title: Add summary table for OS exception <-> errno mapping -> Improve display of OS exception <-> errno mapping
2014-08-12 20:03:21jon.polersetnosy: + jon.poler
messages: + msg225243
2014-08-05 05:35:55ezio.melottisetnosy: + ezio.melotti

type: enhancement
stage: needs patch
2014-07-27 01:53:58ncoghlansetmessages: + msg224094
2014-07-26 18:59:03eric.araujosetnosy: + eric.araujo
messages: + msg224083
2014-07-20 07:02:45ncoghlansetmessages: + msg223500
2014-07-20 07:00:24ncoghlancreate