Add index with links section for built-in functions

[nestor]

BPO	10299
Nosy	@freddrake, @birkenfeld, @terryjreedy, @benjaminp, @ezio-melotti, @merwok
Files	issue10299.diff: 4-columns tables with the functions issue10299-2.diff: 5-columns table with latex-friendly header

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/ezio-melotti'
closed_at = <Date 2010-11-24.22:06:21.630>
created_at = <Date 2010-11-03.14:24:57.387>
labels = ['type-feature', 'docs']
title = 'Add index with links section for built-in functions'
updated_at = <Date 2010-12-02.21:07:21.076>
user = 'https://bugs.python.org/nestor'

bugs.python.org fields:

activity = <Date 2010-12-02.21:07:21.076>
actor = 'georg.brandl'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2010-11-24.22:06:21.630>
closer = 'ezio.melotti'
components = ['Documentation']
creation = <Date 2010-11-03.14:24:57.387>
creator = 'nestor'
dependencies = []
files = ['19478', '19648']
hgrepos = []
issue_num = 10299
keywords = ['patch']
message_count = 18.0
messages = ['120327', '120330', '120539', '120593', '120808', '121583', '122091', '122302', '122304', '122317', '122418', '122419', '122423', '122433', '122448', '122493', '123109', '123116']
nosy_count = 8.0
nosy_names = ['fdrake', 'georg.brandl', 'terry.reedy', 'benjamin.peterson', 'ezio.melotti', 'eric.araujo', 'nestor', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue10299'
versions = ['Python 3.2']

[nestor]

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.

[ezio-melotti]

The attached patch adds a 4-columns table that lists the functions without args.

[terryjreedy]

+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

[merwok]

+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.

[merwok]

Using cell spanning breaks “make latex” (and thus PDF), you may want to rework the reST table markup.

[ezio-melotti]

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.

[merwok]

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.

[ezio-melotti]

Committed in r86732 on py3k, will backport on 3.1/2.7 if Benjamin is OK with that.

[benjaminp]

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\>

---

[ezio-melotti]

Backported in r86735 (3.1) and r86736 (2.7).