Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #55549 > unrolled thread

Use the Source Luke

Back to article view | Back to comp.lang.python

Contents

  Use the Source Luke Raymond Hettinger <python@rcn.com> - 2011-01-28 10:32 -0800
    Re: Use the Source Luke rantingrick <rantingrick@gmail.com> - 2011-01-31 12:45 -0800
    Re: Use the Source Luke rusi <rustompmody@gmail.com> - 2011-01-30 08:50 -0800
    Re: Use the Source Luke Raymond Hettinger <python@rcn.com> - 2011-01-29 12:23 -0800
    Re: Use the Source Luke Paul Rubin <no.email@nospam.invalid> - 2011-01-28 12:30 -0800
    Re: Use the Source Luke rusi <rustompmody@gmail.com> - 2011-02-04 08:58 -0800
    Re: Use the Source Luke Rui Maciel <rui.maciel@gmail.com> - 2011-01-28 20:49 +0000
    Re: Use the Source Luke rantingrick <rantingrick@gmail.com> - 2011-01-31 22:38 -0800
    Re: Use the Source Luke David Boddie <david@boddie.org.uk> - 2011-01-30 14:19 +0100
    Re: Use the Source Luke Giampaolo Rodolà <g.rodola@gmail.com> - 2011-01-28 21:32 +0100
    Re: Use the Source Luke rantingrick <rantingrick@gmail.com> - 2011-01-30 08:42 -0800
    Re: Use the Source Luke Emile van Sebille <emile@fenx.com> - 2011-01-31 14:07 -0800
    Re: Use the Source Luke Tim Wintle <tim.wintle@teamrubber.com> - 2011-01-30 14:47 +0000
      Re: Use the Source Luke Raymond Hettinger <python@rcn.com> - 2011-01-31 12:35 -0800
        Re: Use the Source Luke Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-01-31 22:39 +0000
          Re: Use the Source Luke rusi <rustompmody@gmail.com> - 2011-01-31 22:25 -0800
      Re: Use the Source Luke rusi <rustompmody@gmail.com> - 2011-02-04 08:34 -0800
        Re: Use the Source Luke "OKB (not okblacke)" <brenNOSPAMbarn@NObrenSPAMbarn.net> - 2011-02-04 19:11 +0000
          Re: Use the Source Luke rusi <rustompmody@gmail.com> - 2011-02-04 21:20 -0800
      Re: Use the Source Luke "OKB (not okblacke)" <brenNOSPAMbarn@NObrenSPAMbarn.net> - 2011-02-01 19:32 +0000
    Re: Use the Source Luke Jack Diederich <jackdied@gmail.com> - 2011-01-28 19:02 -0500
      Re: Use the Source Luke Daniel Fetchinson <fetchinson@googlemail.com> - 2011-02-05 12:46 +0100
      Re: Use the Source Luke Raymond Hettinger <python@rcn.com> - 2011-01-28 17:52 -0800
    Re: Use the Source Luke Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-01-30 04:21 +0000
      Re: Use the Source Luke rusi <rustompmody@gmail.com> - 2011-01-29 20:50 -0800
        Re: Use the Source Luke Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2011-01-30 08:53 +0000
    Re: Use the Source Luke Raymond Hettinger <python@rcn.com> - 2011-01-29 21:17 -0800
    Re: Use the Source Luke TP <wingusr@gmail.com> - 2011-01-29 03:22 -0800
    Re: Use the Source Luke Ben Finney <ben+python@benfinney.id.au> - 2011-01-29 10:10 +1100
      Re: Use the Source Luke rusi <rustompmody@gmail.com> - 2011-01-29 19:59 -0800
      Re: Use the Source Luke rusi <rustompmody@gmail.com> - 2011-01-28 23:50 -0800
        Re: Use the Source Luke Ben Finney <ben+python@benfinney.id.au> - 2011-01-30 08:22 +1100

Page 1 of 2  [1] 2  Next page →

#55549 — Use the Source Luke

I hoping a new trend will start with dev's putting direct
source code links in their documentation:

 http://rhettinger.wordpress.com/2011/01/28/open-your-source-more/

I'm looking for more examples of projects that routinely
link their docs back into relavant sections of code.
Have any of you all seen other examples besides
the Go language docs and the Python docs?


Raymond

[toc] | [next] | [standalone]

#55556

On Jan 30, 10:50 am, rusi <rustompm...@gmail.com> wrote:

> I note particularly the disclaimer that it was removed from wikipedia
> [Like when <your-unfavorite-TV-channel> censors stuff you know it
> deserves a second look ;-) ]

Oh you mean that channel that *claims* to provide a specific type of
"programming" however they really provide *anything* but that specific
type of programming! Yes, thank god for you tube.

[toc] | [prev] | [next] | [standalone]

#55577

On Jan 30, 6:19 pm, David Boddie <da...@boddie.org.uk> wrote:

> You might find this page useful:
>
> http://www.wikinfo.org/index.php/Comparison_of_desktop_search_software
>
> David

Thanks for that link David

I note particularly the disclaimer that it was removed from wikipedia
[Like when <your-unfavorite-TV-channel> censors stuff you know it
deserves a second look ;-) ]

[toc] | [prev] | [next] | [standalone]

#55601

On Jan 29, 3:22 am, TP <wing...@gmail.com> wrote:
> On Fri, Jan 28, 2011 at 10:32 AM, Raymond Hettinger <pyt...@rcn.com> wrote:
> > I hoping a new trend will start with dev's putting direct
> > source code links in their documentation:
>
> >  http://rhettinger.wordpress.com/2011/01/28/open-your-source-more/
>
> > I'm looking for more examples of projects that routinely
> > link their docs back into relavant sections of code.
> > Have any of you all seen other examples besides
> > the Go language docs and the Python docs?
>
> > Raymond
> > --
> >http://mail.python.org/mailman/listinfo/python-list
>
> The Sphinx Python Documentation Generator
> (http://sphinx.pocoo.org/index.html), used for documenting lots of
> things other than Python, has an extension called "sphinx.ext.viewcode
> – Add links to highlighted source code"
> (http://sphinx.pocoo.org/ext/viewcode.html).

Thanks, I didn't know about that extension.

To support my effort to add source links to the Python docs,
Georg Brandl added a new directive :source: so that we could
write :source:`Lib/heapq.py` and the set the prefix somewhere else
(i.e. pointing at the py3k branch on subversion or on mercurial).


Raymond

[toc] | [prev] | [next] | [standalone]

#55652

Raymond Hettinger <python@rcn.com> writes:
>  http://rhettinger.wordpress.com/2011/01/28/open-your-source-more/
>
> I'm looking for more examples of projects that routinely
> link their docs back into relavant sections of code.
> Have any of you all seen other examples besides
> the Go language docs and the Python docs?

That is a very good post, and just about 2 days ago I happened to be
looking at the source of heapq for something I was doing, and I think I
got to it through the doc link that you added.  So the link has already
been useful.

Haddock (Haskell's equivalent to Pydoc or Javadoc) can automatically
generate source links in Haskell documentation.  For example, here's the
docs (including source links) for Haskell's standard library for dealing
with lists:

http://www.haskell.org/ghc/docs/7.0-latest/html/libraries/base-4.3.0.0/Data-List.html

I've wanted for a long time for developer-oriented Linux distributions
to include full source code of everything as an integral part of the
distro rather than as a separate distribution.  For example, you could
examine any application and instantly see its source.  All programs
would be compiled with debugging enabled and a way to attach a debugger
to the running process, so you could at any time interrupt the program
and use gdb to see what it was doing, single step it, etc.

[toc] | [prev] | [next] | [standalone]

#55661

On Feb 4, 9:34 pm, rusi <rustompm...@gmail.com> wrote:

>
> [PS Does not read properly in google docs though it reads ok in
> acroread and evince ]

Sorry google docs does not like the pdf
Heres a ps
https://docs.google.com/leaf?id=0B3gsacOF56PxOWUxZTVmOTQtYWIxNy00ZGFjLWEwODUtZDVkM2MyZGI5ZmRk&hl=en

[toc] | [prev] | [next] | [standalone]

#55683

Raymond Hettinger wrote:

> Have any of you all seen other examples besides
> the Go language docs and the Python docs?

Wasn't doxygen developed with that in mind?


Rui Maciel

[toc] | [prev] | [next] | [standalone]

#55692

On Feb 1, 12:25 am, rusi <rustompm...@gmail.com> wrote:

> In short (at the risk of belonging to the equivalence class of others
> whose names start with R) I would suggest a 4th point: Code cruft

Oh rusi, just come out of the closet already we accept you! :-)

[toc] | [prev] | [next] | [standalone]

#55700

On Sunday 30 January 2011 05:21, Steven D'Aprano wrote:

> If I *wanted* to index my files, I could do so, although in
> fairness I'm not aware of any Linux tools which do this -- I know of
> `locate`, which indexes file *names* but not content, and `grep`, which
> searches file content but doesn't index what it finds.

You might find this page useful:

http://www.wikinfo.org/index.php/Comparison_of_desktop_search_software

David

[toc] | [prev] | [next] | [standalone]

#55729

2011/1/28 Raymond Hettinger <python@rcn.com>:
> I hoping a new trend will start with dev's putting direct
> source code links in their documentation:
>
>  http://rhettinger.wordpress.com/2011/01/28/open-your-source-more/
>
> I'm looking for more examples of projects that routinely
> link their docs back into relavant sections of code.
> Have any of you all seen other examples besides
> the Go language docs and the Python docs?
>
>
> Raymond
> --
> http://mail.python.org/mailman/listinfo/python-list
>

Thanks, I think this is a great idea.
I think this definitively should be done for 2.7 documentation as well.

--- Giampaolo
http://code.google.com/p/pyftpdlib/
http://code.google.com/p/psutil/

[toc] | [prev] | [next] | [standalone]

#55733

On Jan 30, 2:53 am, Steven D'Aprano <steve
+comp.lang.pyt...@pearwood.info> wrote:

> In fact, Google
> themselves offer a desktop app that does just that:
>
> http://desktop.google.com/features.html

Yes, but at the expense of your privacy! How much private information
is being sent back to Google plex an used to flash more click ads at
you? Well i guess we could say, google does spam us, but at least we
are more likely to be *slightly* interested in the spam.

[toc] | [prev] | [next] | [standalone]

#55753

On 1/31/2011 12:35 PM Raymond Hettinger said...
> That would explain why fewer people look at the C source code.
>
> However, even the parts of the standard library written in pure Python
> don't seem to be getting read anymore, so I'm still inclined to
> attribute the issue to 1) inconvenient placement of source code,
> 2) a largish code base, and 3) possibly a cultural shift.
>

ISTM that around the time the list forked off py-dev fewer people 
remained that were singing 'use the source'. . .

Emile

[toc] | [prev] | [next] | [standalone]

#55769

On Sat, 2011-01-29 at 21:17 -0800, Raymond Hettinger wrote:
> My thesis is that we can do even better than that by adding
> direct links from the docs to the relevant code with nice
> syntax highlighting.

+1 - I think the source links are very useful (and thanks for pushing
them).


However I think the biggest changes that have probably happened with
python itself are:

 (1) More users for whom this is their first language.
 (2) CS courses / training not teaching C (or pointer-based languages).

(2) is especially important IMO - under half of the python developers I
have regularly worked with would feel comfortable reading C - so for the
other half reading C source code probably isn't going to help them
understand exactly what's going on (although in the long run it might
help them a lot)


Tim Wintle

[toc] | [prev] | [next] | [standalone]

#55836

On Jan 30, 6:47 am, Tim Wintle <tim.win...@teamrubber.com> wrote:
> +1 - I think the source links are very useful (and thanks for pushing
> them).

Happy to do it.

> However I think the biggest changes that have probably happened with
> python itself are:
>
>  (1) More users for whom this is their first language.
>  (2) CS courses / training not teaching C (or pointer-based languages).
>
> (2) is especially important IMO - under half of the python developers I
> have regularly worked with would feel comfortable reading C - so for the
> other half reading C source code probably isn't going to help them
> understand exactly what's going on (although in the long run it might
> help them a lot)

That would explain why fewer people look at the C source code.

However, even the parts of the standard library written in pure Python
don't seem to be getting read anymore, so I'm still inclined to
attribute the issue to 1) inconvenient placement of source code,
2) a largish code base, and 3) possibly a cultural shift.

I'm thinking that all of those can be addressed by efforts
to lower to intellectual investment required to find the
relevant source code.


Raymond

[toc] | [prev] | [next] | [standalone]

#55965

On Mon, 31 Jan 2011 12:35:12 -0800, Raymond Hettinger wrote:

> However, even the parts of the standard library written in pure Python
> don't seem to be getting read anymore, so I'm still inclined to
> attribute the issue to 1) inconvenient placement of source code, 2) a
> largish code base, and 3) possibly a cultural shift.

I'd be inclined to say that #3 is by far the most important. When I 
started programming, the internet wasn't even a distant object on radar. 
(That is to say, it existed, but hardly anyone outside of a few gurus at 
universities had even heard of it.) If you wanted to learn a language, 
you bought a book and read it, if one existed and you could afford it, 
and you read the sample code that came with the software. Often the book 
you bought told you to read the sample code. You couldn't email a mailing 
list to ask for help, or post to a forum, or google the answer. If you 
were lucky, you could go to a Users Group once a month or so. And so "old 
timers" learned to read the source, because that's almost all there was.

Today's newbies take the internet, web forums, mailing lists, usenet and 
google for granted. This is a *big* cultural shift.

As for #1, in truth I don't believe it is actually a problem. Okay, it 
might be a bit inconvenient to find the Python source code the first few 
times you go looking (I can never remember whether to look in
/usr/lib/python or /usr/local/lib/python), but once you've found it, it 
isn't difficult to create a shortcut for it. And as for #2, yes, there 
may be a lot of code in the standard library, but it's all cut up into 
small, easily swallowed chunks called "modules" :)

In my experience, the biggest obstacles for people to read the Python 
code in the standard library are:

(1) thinking to do so in the first place; and

(2) the chicken-and-egg problem that as a newbie they often don't 
understand what they're reading.


Your idea of including links to source in the documentation will 
hopefully help with the first.


-- 
Steven

[toc] | [prev] | [next] | [standalone]

#56047

The following, meant for this thread, went to another my mistake :-)
--------------------------

On Feb 1, 1:35 am, Raymond Hettinger <pyt...@rcn.com> wrote:
> However, even the parts of the standard library written in pure Python
> don't seem to be getting read anymore, so I'm still inclined to
> attribute the issue to 1) inconvenient placement of source code,
> 2) a largish code base, and 3) possibly a cultural shift.


There is another thread running where this was said (by a python
developer?)

> Actually I don't even understand how can IDLE source code quality have
> anything to do with python success or future adoption, as you implied
> in your statements.
> High priority bugs get fixed first. IDLE source code is clearly not a
> high priority issue, hence it doesn't get fixed: end of story.

Now if we can put aside for a moment the fact that the person to whom
this was said specializes in the art of raising others' blood
pressures and making them say what they may not otherwise have said,
it should be clear that this priority is at cross purposes with
Raymond's.

In short (at the risk of belonging to the equivalence class of others
whose names start with R) I would suggest a 4th point: Code cruft

Please note: I am thankful to all python devs for giving me python.
Its just that when functionality becomes as large as it is for python
and the target is fast moving, keeping code spic and span will
generally be perceived to be a priority that has crossed the point of
diminishing returns.  Consequence: noobs will have a higher barrier to
entry than earlier

[toc] | [prev] | [next] | [standalone]

#55937

On Feb 2, 12:32 am, "OKB (not okblacke)"
<brenNOSPAMb...@NObrenSPAMbarn.net> wrote:
> Tim Wintle wrote:
> > (2) is especially important IMO - under half of the python
> > developers I have regularly worked with would feel comfortable
> > reading C - so for the other half reading C source code probably
> > isn't going to help them understand exactly what's going on
> > (although in the long run it might help them a lot)
>
>         I'd just like to note that (2) applies to me in spades.  I'm not
> sure how many other people are in my position, but I use Python because
> I like how it works, and I do not want to use C because I find it
> insufferable.  I quite frequently look at the source of Python modules,
> although more often third-party modules than the standard lib, but if I
> have to look at the C source of something I basically stop and find
> another solution (possibly abandoning Python altogether for that usage).
>
>         I think, in general, the less anyone needs to know C even exists,
> the better for Python; likewise, the more that people have to mention
> the existence of C in a Python context, the worse for Python.  This may
> be a somewhat extreme viewpoint, but that's my position.

In 1990 I wrote a paper elaborating this. http://portal.acm.org/citation.cfm?id=126471
It is dated (before python, java, haskell and the internet as we know
it today)
It is also dated in the sense that I dont totally agree with the
strong views therein (I was half my age then :-)

Still if you want it its here
https://docs.google.com/document/d/1P-BQtpyzjjjOKxzhKjIGI-GLMXW5bOZ6xYBJhApwqLc/edit?hl=en

[PS Does not read properly in google docs though it reads ok in
acroread and evince ]

[toc] | [prev] | [next] | [standalone]

#55993

rusi wrote:

> On Feb 2, 12:32 am, "OKB (not okblacke)"
>>         I think, in general, the less anyone needs to know C even
>> exists, the better for Python; likewise, the more that people have
>> to mention the existence of C in a Python context, the worse for
>> Python.  This may be a somewhat extreme viewpoint, but that's my
>> position. 
> 
> In 1990 I wrote a paper elaborating this.
> http://portal.acm.org/citation.cfm?id=126471 It is dated (before
> python, java, haskell and the internet as we know it today)
> It is also dated in the sense that I dont totally agree with the
> strong views therein (I was half my age then :-)

    	Very interesting, thanks.  I think Python has its own warts 
comparable to some of those you mention, but not all.  What bothers me 
most is when "practicality beats purity" is invoked, with practicality 
defined as "doing it this way is faster in C".

-- 
--OKB (not okblacke)
Brendan Barnwell
"Do not follow where the path may lead.  Go, instead, where there is
no path, and leave a trail."
	--author unknown

[toc] | [prev] | [next] | [standalone]

#56081

On Feb 5, 12:11 am, "OKB (not okblacke)"
<brenNOSPAMb...@NObrenSPAMbarn.net> wrote:
>
>         Very interesting, thanks.  I think Python has its own warts
> comparable to some of those you mention, but not all.  What bothers me
> most is when "practicality beats purity" is invoked, with practicality
> defined as "doing it this way is faster in C".

Yes Knuth is worshipped but his advice is not heeded
http://en.wikipedia.org/wiki/Program_optimization#When_to_optimize

[toc] | [prev] | [next] | [standalone]

#56024

Tim Wintle wrote:

> However I think the biggest changes that have probably happened
> with python itself are:
> 
>  (1) More users for whom this is their first language.
>  (2) CS courses / training not teaching C (or pointer-based
>  languages). 
> 
> (2) is especially important IMO - under half of the python
> developers I have regularly worked with would feel comfortable
> reading C - so for the other half reading C source code probably
> isn't going to help them understand exactly what's going on
> (although in the long run it might help them a lot)

    	I'd just like to note that (2) applies to me in spades.  I'm not 
sure how many other people are in my position, but I use Python because 
I like how it works, and I do not want to use C because I find it 
insufferable.  I quite frequently look at the source of Python modules, 
although more often third-party modules than the standard lib, but if I 
have to look at the C source of something I basically stop and find 
another solution (possibly abandoning Python altogether for that usage).

    	I think, in general, the less anyone needs to know C even exists, 
the better for Python; likewise, the more that people have to mention 
the existence of C in a Python context, the worse for Python.  This may 
be a somewhat extreme viewpoint, but that's my position.

-- 
--OKB (not okblacke)
Brendan Barnwell
"Do not follow where the path may lead.  Go, instead, where there is
no path, and leave a trail."
	--author unknown

[toc] | [prev] | [next] | [standalone]

Page 1 of 2  [1] 2  Next page →

Back to top | Article view | comp.lang.python

csiph-web