classification
Title: improve documentation indexing
Type: enhancement Stage:
Components: Documentation Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bgailer, docs@python, eric.araujo, terry.reedy, tshepang
Priority: normal Keywords:

Created on 2014-04-25 20:27 by bgailer, last changed 2021-04-22 23:37 by iritkatriel.

Messages (2)
msg217170 - (view) Author: bob gailer (bgailer) Date: 2014-04-25 20:27
Inconsistencies / confusion with documentation Index Tab. Example (line numbers added for comments that follow):

1 max
2   built-in function
3 max  (datetime.date attribute)
4   (datetime.datetime attribute)
5   (datetime.time attribute)
6 max() built-in function
7   (decimal.Context method)
8   (decimal.Decimal method)
9   (in module audioloop)

The following all lead to confusion and frustration:
Having 3 rows (1, 3, 6)that begin with max. 
Having an entry (1) that does nothing when double-clicked.
double-clicking (2) takes us to a reference rather than a definition.

RECOMMENDATION:
change to:
max() built-in function
  (sequence operation)
  (decimal.Context method)
  (decimal.Decimal method)
max
  (datetime.date attribute)
  (datetime.datetime attribute)
  (datetime.time attribute)

where double-clicking the first line goes to the max() definition
in 2. Built-in Functions


These comments apply, with a number of variations, to most built-in functions index entries.
msg217808 - (view) Author: √Čric Araujo (eric.araujo) * (Python committer) Date: 2014-05-02 23:58
I have to agree the index pages are often frustrating for me too.

Not sure if this involves code changes in Sphinx itself or if we can improve the markup in the Python docs sources.
History
Date User Action Args
2021-04-22 23:37:10iritkatrielsetversions: + Python 3.11, - Python 2.7, Python 3.4, Python 3.5
2014-05-03 13:57:07tshepangsetnosy: + tshepang
2014-05-02 23:58:02eric.araujosetnosy: + eric.araujo
messages: + msg217808
2014-04-29 04:38:51terry.reedysetnosy: + terry.reedy
2014-04-26 13:08:17pitrousettitle: improve indexing -> improve documentation indexing
2014-04-25 20:34:48zach.waresetversions: - Python 3.1, Python 3.2, Python 3.3
2014-04-25 20:27:41bgailercreate