Make source code links less prominent

[pitrou]

BPO	10858
Nosy	@rhettinger, @abalkin, @pitrou, @benjaminp, @merwok, @bitdancer

^{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/rhettinger'
closed_at = <Date 2011-01-10.03:26:51.843>
created_at = <Date 2011-01-07.18:09:27.887>
labels = ['docs']
title = 'Make source code links less prominent'
updated_at = <Date 2011-01-10.03:26:51.842>
user = 'https://github.com/pitrou'

bugs.python.org fields:

activity = <Date 2011-01-10.03:26:51.842>
actor = 'rhettinger'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2011-01-10.03:26:51.843>
closer = 'rhettinger'
components = ['Documentation']
creation = <Date 2011-01-07.18:09:27.887>
creator = 'pitrou'
dependencies = []
files = []
hgrepos = []
issue_num = 10858
keywords = []
message_count = 10.0
messages = ['125669', '125692', '125699', '125700', '125711', '125712', '125713', '125717', '125821', '125879']
nosy_count = 7.0
nosy_names = ['rhettinger', 'belopolsky', 'pitrou', 'benjamin.peterson', 'eric.araujo', 'r.david.murray', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue10858'
versions = ['Python 2.7', 'Python 3.2']

[pitrou]

Reading library source code will only be enlightening to expert users, since most modules are not academic but real-world implementations, with all the complications it entails. Therefore, putting a link at the top of module sections is only confusing for most people. I would like to shift these links to the bottom of doc pages, where we already have "see also" links to RFCs and the like.

[bitdancer]

+1

[rhettinger]

Please leave these alone for the time being. I put them high on the page so that people would have a consistent and easy to find view-source link. It is an experiment and time will tell whether it was a good choice. For the time being, I don't want it buried.

The goal is to reacquaint people with the source as an adjunct to the docs. The phrase use-the-source-luke used to be common in the python community but now many devs don't seem to be able to readily access the source (with it tucked away in a library directory).

[pitrou]

The goal is to reacquaint people with the source as an adjunct to the
docs. The phrase use-the-source-luke used to be common in the python
community but now many devs don't seem to be able to readily access
the source (with it tucked away in a library directory).

I don't think someone "not able to readily access the source" from a
link at the *bottom* of a doc page would be able to understand (or even
be motivated to understand) the stdlib's source code.

While I understand the motivation to encourage reading of the source
code, this should not disrupt the sequential reading of documentation
pages, or make it seem more important than the API docs themselves.

[abalkin]

As Raymond explained, he added these links as a kind of social experiment and this issue itself shows that it works. :-)

I have a few suggestions on how to make these links more useful:

1. A ViewVC link is the simplest solution to present the source, but the way it presents the source code looks foreign to sphinx docs. It would be better if the source was formatted similarly to the source examples embedded in doc pages.

2. It would be great to have at least module names hyperlinked in the source views to aid code navigation.

3. I would rather see source links appear consistently for each module and not just for an ad-hoc selection.

4. The side bar already has a "Show Source" link which takes to the reST source of the page. I don't think this is very useful. Maybe this link should point to the Python source or a separate "python source" link should appear next to it.

[pitrou]

I have a few suggestions on how to make these links more useful:

The question is not how they could be more useful, but *whether* they
are useful at all. An user skilled enough to read the source code is
probably skilled enough not to require a prominently displayed link at
the top of each doc page.

I agree that visual appearance of the ViewVC pages could be better but
that's a separate issue altogether.

[merwok]

1: I hope this will just be a matter of using the same Pygments theme in Sphinx and hgweb.

2: I don’t think hgweb can do that. Mercurial being extensible, this addition may be a fun project.

3: Not all modules are good examples (see threading for some unelegant code), so I support ad-hoc selection. I also support the real fix of improving the quality of every module, but that’s longer-term. :)

4: “Show Source” is a link that is easily overlooked IMO, a seealso section makes me think people will actually see the link. There is also the minor concern of breaking expectations of people accustomed to Sphinx.

[abalkin]

On Fri, Jan 7, 2011 at 4:32 PM, Éric Araujo <report@bugs.python.org> wrote:
..

3: Not all modules are good examples (see threading for some unelegant code), so I support ad-hoc selection.

The problem with ad-hoc selection is that it adds maintenance burden
(someone has to make a call) and it is inherently subjective. For
example, I find dis.py source code rather uninspiring while
pickletools.py has a trove of valuable information about pickle
opcodes that is not available elsewhere.

 I also support the real fix of improving the quality of every module, but that’s longer-term. :)

Having the sources on "public display" may help achieving this goal.

4: “Show Source” is a link that is easily overlooked IMO, a seealso section makes me think people
will actually see the link.

A side-bar link may be in addition to the more prominent but less
common "See also" links. If the source navigation becomes available,
we can also add inconspicuous links to function sectoins that would
take you directly to the function source code.

[benjaminp]

I'm curious as to how the experiment is being carried out and how conclusions will be drawn.

[rhettinger]

Removed the wordy and bright yellow boxes.
Replace with single source link just below the section heading.
Style modeled after that used in the Go language docs http://golang.org/pkg/container/heap/

See r87898.