[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 <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
É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 <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti stage: -> needs patch type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
Changes by Brett Cannon <brett@python.org>: ---------- nosy: +brett.cannon _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22014> _______________________________________
Brett Cannon <brett@python.org> added the comment: Is this still important now that OSError has so many subclasses that correspond to specific error codes? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue22014> _______________________________________
participants (5)
-
Brett Cannon -
Ezio Melotti
-
Jon Poler
-
Nick Coghlan
-
Éric Araujo