classification
Title: Add index with links section for built-in functions
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: benjamin.peterson, docs@python, eric.araujo, ezio.melotti, fdrake, georg.brandl, nestor, terry.reedy
Priority: normal Keywords: patch

Created on 2010-11-03 14:24 by nestor, last changed 2010-12-02 21:07 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
issue10299.diff ezio.melotti, 2010-11-03 17:03 4-columns tables with the functions review
issue10299-2.diff ezio.melotti, 2010-11-20 00:16 5-columns table with latex-friendly header
Messages (18)
msg120327 - (view) Author: nestor (nestor) Date: 2010-11-03 14:24
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.
msg120330 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-11-03 17:03
The attached patch adds a 4-columns table that lists the functions without args.
msg120539 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-11-05 21:48
+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
msg120593 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-06 07:18
+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.
msg120808 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-08 21:56
Using cell spanning breaks “make latex” (and thus PDF), you may want to rework the reST table markup.
msg121583 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-11-20 00:16
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.
msg122091 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-22 04:28
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.
msg122302 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-11-24 20:22
Committed in r86732 on py3k, will backport on 3.1/2.7 if Benjamin is OK with that.
msg122304 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2010-11-24 20:25
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>
> _______________________________________
>
msg122317 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-11-24 22:06
Backported in r86735 (3.1) and r86736 (2.7).
msg122418 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-25 23:44
In 2.7, the functions are not sorted alphabetically.  I think they should, and I offer to do the boring work.
msg122419 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-11-25 23:48
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-functions
msg122423 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-26 00:49
It’s fine to have them at the end of the page, but I think people want things to be sorted in an index.
msg122433 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2010-11-26 03:55
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).
msg122448 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-11-26 11:41
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.
msg122493 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-27 01:02
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.
msg123109 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-02 20:35
By the way, I wonder why this page is named “functions” and the one for “builtins” is nearly empty.
msg123116 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-12-02 21:07
That's legacy from the good old latex days.
History
Date User Action Args
2010-12-02 21:07:21georg.brandlsetmessages: + msg123116
2010-12-02 20:35:22eric.araujosetmessages: + msg123109
2010-11-27 01:02:33eric.araujosetmessages: + msg122493
2010-11-26 11:41:09georg.brandlsetmessages: + msg122448
2010-11-26 03:55:58ezio.melottisetmessages: + msg122433
2010-11-26 00:49:57eric.araujosetmessages: + msg122423
2010-11-25 23:48:13ezio.melottisetmessages: + msg122419
2010-11-25 23:44:30eric.araujosetmessages: + msg122418
2010-11-24 22:06:21ezio.melottisetstatus: open -> closed
resolution: fixed
messages: + msg122317

stage: patch review -> resolved
2010-11-24 20:25:46benjamin.petersonsetmessages: + msg122304
2010-11-24 20:22:09ezio.melottisetnosy: + benjamin.peterson
messages: + msg122302
2010-11-22 04:28:22eric.araujosetmessages: + msg122091
2010-11-20 00:16:05ezio.melottisetfiles: + issue10299-2.diff

messages: + msg121583
2010-11-08 21:56:45eric.araujosetmessages: + msg120808
2010-11-06 07:18:23eric.araujosetnosy: + eric.araujo
messages: + msg120593
2010-11-05 21:48:09terry.reedysetnosy: + terry.reedy
messages: + msg120539
2010-11-03 17:10:51fdrakesetnosy: + fdrake
2010-11-03 17:03:20ezio.melottisetfiles: + issue10299.diff
messages: + msg120330

assignee: docs@python -> ezio.melotti
keywords: + patch
stage: needs patch -> patch review
2010-11-03 14:26:57ezio.melottisetnosy: + ezio.melotti

stage: needs patch
2010-11-03 14:24:57nestorcreate