[issue10299] Add index with links section for built-in functions
New submission from nestor <nestornissen@gmail.com>: The built-in function page (http://docs.python.org/dev/py3k/library/functions.html) is pretty long. Each function has an anchor but unlike the built-in types section there is no quick way to get an overview or jump to a specific function (like open or print) short of scrolling through 22 pages. It would be nice to have an index of all built-in functions linked to the specific entry on the built-in functions page. This could be either somehow added to the index page (http://docs.python.org/dev/py3k/library/index.html) or to the top of the built-in functions page itself. For efficient use of real-estate multiple function names could be on one single line alphabetically sorted and separated by spaces. ---------- assignee: docs@python components: Documentation messages: 120327 nosy: docs@python, georg.brandl, nestor priority: normal severity: normal status: open title: Add index with links section for built-in functions type: feature request versions: Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti stage: -> needs patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: The attached patch adds a 4-columns table that lists the functions without args. ---------- assignee: docs@python -> ezio.melotti keywords: +patch stage: needs patch -> patch review Added file: http://bugs.python.org/file19478/issue10299.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Changes by Fred L. Drake, Jr. <fdrake@acm.org>: ---------- nosy: +fdrake _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: +1 from me on a table at the top of the functions page. I am assuming that the markup will induce hotlinks. The main problem I see is the need to hand rewrite when another function is added ---------- nosy: +terry.reedy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: +1 on the general idea. I applied the patch and built the documentation to see what the output looks like: The hotlinks are here and work, that’s cool, but I think the table wastes space. You could use five columns without damaging usability (that is, summoning the hateful horizontal scrollbar), even in 800×600 with an uncollapsed sidebar. Alternative ideas like using a special unordered list with automatic CSS 3 flowing or replacing the manual table with a new Sphinx directive would take a lot of time, so consider I’m +1 on whatever you decide best. ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Using cell spanning breaks “make latex” (and thus PDF), you may want to rework the reST table markup. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Here's a new patch with a 5 column tables. I had to use some rst trickery to make a decent header that works both in the HTML and Latex outputs. I put the title in the middle cell (the 3rd) of the header and left the others empty. The column cells are a little wider but they are still OK at 800x600. Éric how do you like this version? I could also drop the header altogether, but I don't like the headless table too much. ---------- Added file: http://bugs.python.org/file19648/issue10299-2.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: I like this version. HTML and LaTex build without warning; all-pdf takes forever and spits out a metric ton of messages, so I haven’t checked its result. The markup trickery is unfortunate, though, I’d like a pronouncement from Georg about that. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Committed in r86732 on py3k, will backport on 3.1/2.7 if Benjamin is OK with that. ---------- nosy: +benjamin.peterson _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Benjamin Peterson <benjamin@python.org> added the comment: Okay. 2010/11/24 Ezio Melotti <report@bugs.python.org>:
Ezio Melotti <ezio.melotti@gmail.com> added the comment:
Committed in r86732 on py3k, will backport on 3.1/2.7 if Benjamin is OK with that.
---------- nosy: +benjamin.peterson
_______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: Backported in r86735 (3.1) and r86736 (2.7). ---------- resolution: -> fixed stage: patch review -> committed/rejected status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: In 2.7, the functions are not sorted alphabetically. I think they should, and I offer to do the boring work. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: The last 4 functions are "Non-essential Built-in Functions"[0] so I kept them at the end of the list to match the order they have in the page. [0]: http://docs.python.org/library/functions.html#non-essential-built-in-functio... ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: It’s fine to have them at the end of the page, but I think people want things to be sorted in an index. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Ezio Melotti <ezio.melotti@gmail.com> added the comment: I don't think it's worth changing it. The table still provides a good overview, and having them at the end won't prevent people to find their doc. Both the table and the page could be divided in sections though, if we find a way to group all the functions that makes enough sense (e.g. put together int/dict/list/set/etc, getattr/setattr/delattr, but then it's difficult to add more groups without maxing them too small). ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Georg Brandl <georg@python.org> added the comment: Dividing the table in sections makes sense to me; it provides the kind of grouping that is helpful sometimes, but cannot be kept when sorting alphabetically. So when the table is grouped, the actual docs can remain alphabetized. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Possible groups: Types constructors: bool, bytearray, bytes, complex, dict, float, frozenset, int, list, memoryview, object, range, set, slice, str, tuple Mathematical functions: abs, bin, divmod, hex, oct, pow, round Working with sequences: all, any, enumerate, filter, iter, len, map, max, min, reversed, sorted, sum, zip Working with strings: chr, format, ord I/O: input, open, print Introspection/metaprogramming: ascii, delattr, dir, getattr, globals, hasattr, help, id, isinstance, issubclass, locals, repr, setattr, type, vars Advanced functions: classmethod, compile, eval, exec, hash, next, property, staticmethod, super, __import__ The last two are debatable. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: By the way, I wonder why this page is named “functions” and the one for “builtins” is nearly empty. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
Georg Brandl <georg@python.org> added the comment: That's legacy from the good old latex days. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue10299> _______________________________________
participants (7)
-
Benjamin Peterson -
Ezio Melotti
-
Fred L. Drake, Jr.
-
Georg Brandl
-
nestor
-
Terry J. Reedy
-
Éric Araujo