Re: Python-by-example - new online guide to Python Standard Library
On Apr 3, 8:33 pm, AK <[EMAIL PROTECTED]> wrote: > AK wrote: > > Hello, > > > I find that I learn easier when I go from specific examples to a more > > general explanation of function's utility and I made a reference guide > > that will eventually document all functions, classes and methods in > > Python's Standard Library. For now, I covered about 20 most important > > modules. I will be adding more modules and eventually I'll cover > > everything. Here's my progress so far, let me know if this is useful; > > I'll be glad to hear comments/suggestions/etc: > > >http://www.lightbird.net/py-by-example/ > > I uploaded an updated site incorporating most of the suggestions I > received and fixing some errors along the way. I will be adding more > examples to modules that are already covered and will try to add more > modules during the following week. Thanks again to all who posted advice > and comments! > I don't know if you've heard of Sphinx, it's being used to generate the Python 2.6 docs but can also be used standalone. It may have benefits for a project like yours, particularly with regard to collaboration and maintainability over the long-term. I've been playing about with it myself and put together a `very` basic site using a few of the pages from your site: The generated html is here: http://gflanagan.net/site/python/pbe/pbe-sphinx-skeleton-build-0.1.tar.gz http://gflanagan.net/site/python/pbe/pbe-sphinx-skeleton-build-0.1.zip And the actual Sphinx 'app': http://gflanagan.net/site/python/pbe/pbe-sphinx-skeleton-0.1.tar.gz http://gflanagan.net/site/python/pbe/pbe-sphinx-skeleton-0.1.zip For which you would need Sphinx (obviously): http://sphinx.pocoo.org/ which depends on docutils: http://docutils.sourceforge.net/ and pygments: http://pygments.org/ There's a make.bat for windows and a MakeFile for unix but the latter is untested. I've no time to spend on it further, but you're welcome to what's there if you've any interest. (I repeat, it's just a proof of concept - don't expect too much.) As you might see, I preferred 'doctest' style code rather than the commented results, but each to their own. Sphinx uses ReST as its input format - below is what I cooked up for 'restifying' your html, not perfect but a brave attempt! All the best. Gerard -- import textwrap import re import os from BeautifulSoup import BeautifulSoup def onmatch(m): return '\nRESULT' + m.group(2) result = re.compile('(# )?(.*?)', re.DOTALL | re.MULTILINE) src = 'c:/workspace/pbe/orig/' for infile in os.listdir(src): if not infile.endswith('-module.html'): continue title = infile[:-5] infile = src + infile outfile = infile[:-4] + 'rst' out = open(outfile, 'wb') out.write(title + '\n') out.write('='*len(title) + '\n\n') soup = BeautifulSoup(open(infile).read()) for p in soup.findAll('ul'): print >> out for line in textwrap.wrap(p.span.contents[0], 79): print >> out, line.lstrip() #code = ''.join(comment.sub(onmatch, str(p.pre))) code = result.sub(onmatch, str(p.pre)).splitlines()[1:-1] if code: print >> out print >> out, '::' print >> out for line in code: line = line.strip() if line: leader = '' if line.startswith('RESULT'): line = line[len('RESULT'):] else: leader += '>>> ' print >> out, leader + line else: print >> out print >> out out.close() -- -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
ivan wrote: > Very cool. > Have you thought about making a printable version that doesn't wrap > any lines that shouldn't be and has page breaks at good spots? > > -- > ivan Hi ivan, I will work on that after I finalize modules that are already there. I think this would be better than having people print out the guide and then either have print out again in a couple of weeks or stuck with using a very outdated guide. So, I think it will be one to three weeks at most before printable version is available.. Glad you like Python by Example! thx, -- -ak Tobu | http://tobu.lightbird.net/ | Freeform DB / Tagger / PIM Python-by-Example | http://pbe.lightbird.net/ | Guide to LibRef -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
Very cool. Have you thought about making a printable version that doesn't wrap any lines that shouldn't be and has page breaks at good spots? -- ivan -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
shurik wrote: > that's great! thanks for putting this together. what about the inspect > module? and particularly getsource :) > Glad you like it! I will add every module eventually, but I'll put inspect up on top of todo list. -- -ak Tobu | http://tobu.lightbird.net/ | Freeform DB / Tagger / PIM Python-by-Example | http://pbe.lightbird.net/ | Guide to LibRef -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
that's great! thanks for putting this together. what about the inspect module? and particularly getsource :) On Apr 1, 6:15 pm, AK <[EMAIL PROTECTED]> wrote: > Hello, > > I find that I learn easier when I go from specific examples to a more > general explanation of function's utility and I made a reference guide > that will eventually document all functions, classes and methods in > Python's Standard Library. For now, I covered about 20 most important > modules. I will be adding more modules and eventually I'll cover > everything. Here's my progress so far, let me know if this is useful; > I'll be glad to hear comments/suggestions/etc: > > http://www.lightbird.net/py-by-example/ > > -- > -ak > Tobu |http://www.lightbird.net/tobu/| Freeform DB / Tagger / PIM -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
On 2 Apr, 03:15, AK <[EMAIL PROTECTED]> wrote: > Hello, > > I find that I learn easier when I go from specific examples to a more > general explanation of function's utility and I made a reference guide > that will eventually document all functions, classes and methods in > Python's Standard Library. For now, I covered about 20 most important > modules. I will be adding more modules and eventually I'll cover > everything. Here's my progress so far, let me know if this is useful; > I'll be glad to hear comments/suggestions/etc: > > http://www.lightbird.net/py-by-example/ > > -- > -ak > Tobu |http://www.lightbird.net/tobu/| Freeform DB / Tagger / PIM Great idea! Thanks a lot for you work. --- Giampaolo http://code.google.com/p/pyftpdlib -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
AK wrote: > > I uploaded an updated site incorporating most of the suggestions I > received and fixing some errors along the way. I will be adding more > examples to modules that are already covered and will try to add more > modules during the following week. Thanks again to all who posted advice > and comments! > I also mapped the site to a subdomain so that it's easier to access quickly: http://pbe.lightbird.net/ where 'pbe' stands for 'Python-by-Example'. -- -ak Tobu | http://tobu.lightbird.net/ | Freeform DB / Tagger / PIM Python-by-Example | http://pbe.lightbird.net/ | Guide to LibRef -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
AK wrote: > Hello, > > I find that I learn easier when I go from specific examples to a more > general explanation of function's utility and I made a reference guide > that will eventually document all functions, classes and methods in > Python's Standard Library. For now, I covered about 20 most important > modules. I will be adding more modules and eventually I'll cover > everything. Here's my progress so far, let me know if this is useful; > I'll be glad to hear comments/suggestions/etc: > > http://www.lightbird.net/py-by-example/ > I uploaded an updated site incorporating most of the suggestions I received and fixing some errors along the way. I will be adding more examples to modules that are already covered and will try to add more modules during the following week. Thanks again to all who posted advice and comments! -- -ak Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM Python-by-Example | http://www.lightbird.net/py-by-example/ | Guide to LibRef -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
CM wrote: > On Apr 2, 2:50 pm, AK <[EMAIL PROTECTED]> wrote: >> Terry Reedy wrote: >>> "AK" <[EMAIL PROTECTED]> wrote in message >>> news:[EMAIL PROTECTED] >>> || I'll be glad to hear comments/suggestions/etc: >>> | >>> |http://www.lightbird.net/py-by-example/ >>> Using - as the example/return delimiter does not work. >>> If you do not want to substantially lengthen the document by going to >> sqrt(9) >>> 3 >>> then use Python's a comment symbol. >>> sqrt(9) # 3 >>> -or- >>> sqrt(9) # returns 3 (but I think I prefer the first) >>> which clearly is not an arithmetic expression and which can be >>> cut-and-pasted into the interactive interpreter. This also works nicely >>> for invalid examples. >>> sqrt(-9) # raises ValueError >>> Terry Jan Reedy >> Thanks to everybody who replied, I will implement the change as per >> Terry's advice. I'm still considering whether to use the standard >> interpreter syntax, i.e. >>> ... \n result; my reason for not doing that >> is that I will often have a whole screen of function / result lines and >> if I were to add a new line for the result, that'd make two pages out of >> one, which I think is a bit too much. In current docs there are not so >> many examples, so that space is not multiplied quite so much, and using >> interactive interpreter way of showing result is not nearly as much of >> a problem. However, I'm still thinking this over and it seems that >> almost everyone wants to see it done in that way, I might still go for >> two lines. I'll also be posting updates as the work progresses.. >> >> thx, >> >> -- >> -ak >>Tobu |http://www.lightbird.net/tobu/| Freeform DB / Tagger / PIM >>Python-by-Example |http://www.lightbird.net/py-by-example/| Guide >> to LibRef > > You should also change the look of the page to be more high-contrast. > The grayish text in a gray box and the light green text...all too > subtle to see. Not easy for well-sighted people let alone those with > poorer vision. Try make things visually very obvious, bolded headers, > etc. If so, and with the change of showing the result not with an "-" > symbol, it will be much stronger. Thank you for doing it. Okay, will do. In fact this is the second time in as many days that I get a comment on my proposed designs to use more contrasted text vs. background (in fact, for the other design about 3-4 people mentioned this topic). I really had no idea many people have trouble with that. To me, less contrasted text looks smoother and more aesthetically pleasing to the eye, unless I have to read 3 pages or more of condensed text. I also do eye excercises religiously every day:-), so this may train the eyes to see small details better, but I design for other people to use, therefore I will of course try to make it as easy to read for as many people as possible.. Thanks for the comment! I will update the site tomorrow morning with all the changes.. -- -ak Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM Python-by-Example | http://www.lightbird.net/py-by-example/ | Guide to LibRef -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
On Apr 2, 2:50 pm, AK <[EMAIL PROTECTED]> wrote: > Terry Reedy wrote: > > "AK" <[EMAIL PROTECTED]> wrote in message > >news:[EMAIL PROTECTED] > > > || I'll be glad to hear comments/suggestions/etc: > > | > > |http://www.lightbird.net/py-by-example/ > > > Using - as the example/return delimiter does not work. > > If you do not want to substantially lengthen the document by going to > > sqrt(9) > > 3 > > > then use Python's a comment symbol. > > > sqrt(9) # 3 > > -or- > > sqrt(9) # returns 3 (but I think I prefer the first) > > > which clearly is not an arithmetic expression and which can be > > cut-and-pasted into the interactive interpreter. This also works nicely > > for invalid examples. > > > sqrt(-9) # raises ValueError > > > Terry Jan Reedy > > Thanks to everybody who replied, I will implement the change as per > Terry's advice. I'm still considering whether to use the standard > interpreter syntax, i.e. >>> ... \n result; my reason for not doing that > is that I will often have a whole screen of function / result lines and > if I were to add a new line for the result, that'd make two pages out of > one, which I think is a bit too much. In current docs there are not so > many examples, so that space is not multiplied quite so much, and using > interactive interpreter way of showing result is not nearly as much of > a problem. However, I'm still thinking this over and it seems that > almost everyone wants to see it done in that way, I might still go for > two lines. I'll also be posting updates as the work progresses.. > > thx, > > -- > -ak >Tobu |http://www.lightbird.net/tobu/| Freeform DB / Tagger / PIM >Python-by-Example |http://www.lightbird.net/py-by-example/| Guide > to LibRef You should also change the look of the page to be more high-contrast. The grayish text in a gray box and the light green text...all too subtle to see. Not easy for well-sighted people let alone those with poorer vision. Try make things visually very obvious, bolded headers, etc. If so, and with the change of showing the result not with an "-" symbol, it will be much stronger. Thank you for doing it. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
Terry Reedy wrote: > "AK" <[EMAIL PROTECTED]> wrote in message > news:[EMAIL PROTECTED] > > || I'll be glad to hear comments/suggestions/etc: > | > | http://www.lightbird.net/py-by-example/ > > Using - as the example/return delimiter does not work. > If you do not want to substantially lengthen the document by going to > sqrt(9) > 3 > > then use Python's a comment symbol. > > sqrt(9) # 3 > -or- > sqrt(9) # returns 3 (but I think I prefer the first) > > which clearly is not an arithmetic expression and which can be > cut-and-pasted into the interactive interpreter. This also works nicely > for invalid examples. > > sqrt(-9) # raises ValueError > > Terry Jan Reedy > > > > > > > Thanks to everybody who replied, I will implement the change as per Terry's advice. I'm still considering whether to use the standard interpreter syntax, i.e. >>> ... \n result; my reason for not doing that is that I will often have a whole screen of function / result lines and if I were to add a new line for the result, that'd make two pages out of one, which I think is a bit too much. In current docs there are not so many examples, so that space is not multiplied quite so much, and using interactive interpreter way of showing result is not nearly as much of a problem. However, I'm still thinking this over and it seems that almost everyone wants to see it done in that way, I might still go for two lines. I'll also be posting updates as the work progresses.. thx, -- -ak Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM Python-by-Example | http://www.lightbird.net/py-by-example/ | Guide to LibRef -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
"AK" <[EMAIL PROTECTED]> wrote in message news:[EMAIL PROTECTED] || I'll be glad to hear comments/suggestions/etc: | | http://www.lightbird.net/py-by-example/ Using - as the example/return delimiter does not work. If you do not want to substantially lengthen the document by going to >>> sqrt(9) 3 then use Python's a comment symbol. sqrt(9) # 3 -or- sqrt(9) # returns 3 (but I think I prefer the first) which clearly is not an arithmetic expression and which can be cut-and-pasted into the interactive interpreter. This also works nicely for invalid examples. sqrt(-9) # raises ValueError Terry Jan Reedy -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
On Apr 1, 10:15 pm, AK <[EMAIL PROTECTED]> wrote: > Hello, Hiya > I find that I learn easier when I go from specific examples to a more > general explanation of function's utility and I made a reference guide > that will eventually document all functions, classes and methods in > Python's Standard Library. Thanks a lot, this is a great resource. > For now, I covered about 20 most important > modules. I will be adding more modules and eventually I'll cover > everything. Here's my progress so far, let me know if this is useful; > I'll be glad to hear comments/suggestions/etc: > > http://www.lightbird.net/py-by-example/ > Content is nice, presentation can be tweaked towards making examples easier to understand and run on the interactive console. I suggest taking a look at PyMOTW[1] and Crunchy[2][3] for nice ideas. Best regards, Daniel [1] http://www.doughellmann.com/projects/PyMOTW/ [2] http://code.google.com/p/crunchy/ [3] http://us.pycon.org/2008/conference/schedule/event/46/ -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
Why don't use the normal Python shell syntax as used by doctest? >>> abs(-5.5) 5.5 That would be much more readable. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
Indeed, the first thing I saw on the front page was "math.sqrt(9) - 3.0". Ok, I thought, random arithmetic expression, so what? There is already a standard way of showing a piece of code and its results. It's the interactive prompt: >>> import math >>> math.sqrt(9) 3.0 >>> Tada! On Apr 2, 12:43 pm, GHUM <[EMAIL PROTECTED]> wrote: > Tobu, > > I like this idea. Deducting from an example is really another way to > wisdom. > > What struck me as most diffuclt to understand: > > abs(-5.5) - 5.5 > > -> you are using "-" as symbol for "will give the result", which is > really, really hard to parse. Take something else, please. Unicode has > THAT many cool symbols. Or just -> or -=> or whatever. > > Thanks for sharing that work! > > Harald -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
On Apr 2, 2:43 pm, GHUM <[EMAIL PROTECTED]> wrote: > Tobu, > > I like this idea. Deducting from an example is really another way to > wisdom. > > What struck me as most diffuclt to understand: > > abs(-5.5) - 5.5 > > -> you are using "-" as symbol for "will give the result", which is > really, really hard to parse. Take something else, please. Unicode has > THAT many cool symbols. Or just -> or -=> or whatever. > > Thanks for sharing that work! > > Harald Or just use comments to indicate text that tells what the code does. I too agree you need to change the '-'. -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
Tobu, I like this idea. Deducting from an example is really another way to wisdom. What struck me as most diffuclt to understand: abs(-5.5) - 5.5 -> you are using "-" as symbol for "will give the result", which is really, really hard to parse. Take something else, please. Unicode has THAT many cool symbols. Or just -> or -=> or whatever. Thanks for sharing that work! Harald -- http://mail.python.org/mailman/listinfo/python-list
Re: Python-by-example - new online guide to Python Standard Library
Learning by example is the best. I remember working through a book when I was little called "Qbasic by Example." On Tue, Apr 1, 2008 at 9:15 PM, AK <[EMAIL PROTECTED]> wrote: > Hello, > > I find that I learn easier when I go from specific examples to a more > general explanation of function's utility and I made a reference guide > that will eventually document all functions, classes and methods in > Python's Standard Library. For now, I covered about 20 most important > modules. I will be adding more modules and eventually I'll cover > everything. Here's my progress so far, let me know if this is useful; > I'll be glad to hear comments/suggestions/etc: > > http://www.lightbird.net/py-by-example/ > > -- > -ak > Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM > -- > http://mail.python.org/mailman/listinfo/python-list > -- http://mail.python.org/mailman/listinfo/python-list
Python-by-example - new online guide to Python Standard Library
Hello, I find that I learn easier when I go from specific examples to a more general explanation of function's utility and I made a reference guide that will eventually document all functions, classes and methods in Python's Standard Library. For now, I covered about 20 most important modules. I will be adding more modules and eventually I'll cover everything. Here's my progress so far, let me know if this is useful; I'll be glad to hear comments/suggestions/etc: http://www.lightbird.net/py-by-example/ -- -ak Tobu | http://www.lightbird.net/tobu/ | Freeform DB / Tagger / PIM -- http://mail.python.org/mailman/listinfo/python-list