[issue22014] Add summary table for OS exception <-> errno mapping
New submission from Nick Coghlan:
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)
----------
assignee: docs@python
components: Documentation
keywords: easy
messages: 223499
nosy: docs@python, ncoghlan
priority: normal
severity: normal
status: open
title: Add summary table for OS exception <-> errno mapping
versions: Python 3.4, Python 3.5
_______________________________________
Python tracker
Nick Coghlan added the comment:
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.
----------
_______________________________________
Python tracker
Éric Araujo added the comment:
literalinclude lets you select only some lines of the file: http://sphinx-doc.org/markup/code.html#includes
----------
nosy: +eric.araujo
_______________________________________
Python tracker
Nick Coghlan added the comment:
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.
----------
_______________________________________
Python tracker
Changes by Ezio Melotti
Jon Poler added the comment:
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.
----------
nosy: +jon.poler
_______________________________________
Python tracker
Nick Coghlan added the comment:
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.
----------
title: Add summary table for OS exception <-> errno mapping -> Improve display of OS exception <-> errno mapping
_______________________________________
Python tracker
Jon Poler added the comment:
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.
----------
keywords: +patch
Added file: http://bugs.python.org/file36365/OS_exceptions_table.patch
_______________________________________
Python tracker
Jon Poler added the comment:
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.
----------
Added file: http://bugs.python.org/file36392/os_exceptions_table_V2.patch
_______________________________________
Python tracker
Changes by Brett Cannon
Brett Cannon
participants (5)
-
Brett Cannon -
Ezio Melotti
-
Jon Poler
-
Nick Coghlan
-
Éric Araujo