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)

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.

literalinclude lets you select only some lines of the file: http://sphinx-doc.org/markup/code.html#includes

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.

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.

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.

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.

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.

Is this still important now that OSError has so many subclasses that correspond to specific error codes?