Python-by-example - new online guide to Python Standard Library

[Gerard Flanagan]

On Apr 3, 8:33 pm, AK <andrei.... at gmail.com> 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('<span class="result">(# )?(.*?)</span>',
                                        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()
------------------------------------------------------------------