Redesign of Python site

[Bengt Richter]

On Tue, 9 Sep 2003 14:06:22 -0500, Skip Montanaro <skip at pobox.com> wrote:

>
>    amk> I envision people wanting information on a specific version first,
>    amk> only later going to the more generic items under "documentation".
>    amk> Do other people think this would be a good idea?
>
>I think docs are more important than specific versions.  Sure, the first
>time they come to the site they'll be looking for "Python 2.3".  But most
>times after that they'll want documentation.  The most frequent page I visit
>on the site is
>
>    http://www.python.org/dev/doc/devel/modindex.html
>
>That far outpaces any other page on the site, even the home page, so I
>bookmarked so it's one click away.
>
For the most part, I use downloaded HTML docs from my HD. And a command line
hack to search with regex the index page for links to the individual module docs
and/or launch the browser to a particular doc. E.g., (the opts handling code is a bit weird,
just a quick experiment, not meant as a model ;-)

[ 7:36] C:\pywk\clp>modoc

Usage: modoc.py [-h] [-re | -ire ] [-href] pattern
    Without opts, pattern is taken as a module name to start browser showing docs for.
    With opt(s):
      -re: pattern is taken as regex to print available matching doc names
      -ire: same as -re but case insensitive
      -href: prints doc href paths along with names found.
      -h: print this

Doc info is retrieved from the html file defined by environment name PY_DOC_INDEX,
e.g., modindex.html  and this is located (along with pages therefrom referenced)
by prefixing the string defined by PY_DOC_PREFIX, e.g., D:/Python23/Doc/ (note
forward slashing and ending slash). The ref_name_patt regex may need change if
generated documentation links change format.

[ 7:37] C:\pywk\clp>modoc -ire os
MacOS               TERMIOS             macostools          os
os.path             ossaudiodev         posix               posixfile
termios
[ 7:37] C:\pywk\clp>modoc -re os
macostools          os                  os.path             ossaudiodev
posix               posixfile           termios
[ 7:37] C:\pywk\clp>modoc os.path

(browser pops up with os.path doc).

Oh, I forgot:

[ 7:39] C:\pywk\clp>modoc -re os -href
         macostools: 'mac/module-macostools.html'
                 os: 'lib/module-os.html'
            os.path: 'lib/module-os.path.html'
        ossaudiodev: 'lib/module-ossaudiodev.html'
              posix: 'lib/module-posix.html'
          posixfile: 'lib/module-posixfile.html'
            termios: 'lib/module-termios.html'

I was thinking of expanding it to cover more of the doc hierarchy, but never got a round tuit.
In case someone want to use/improve it:
(Note the
    PY_DOC_PREFIX = os.environ.get('PY_DOC_PREFIX', r'D:/Python23/Doc/')
    PY_DOC_INDEX  = os.environ.get('PY_DOC_INDEX',  r'modindex.html')
lines, which you may want to change for your system setup).

----< modoc.py >---------------------------------------------------------------------------
# modoc.py -- quick way to get to module docs from command line
"""
Usage: modoc.py [-h] [-re | -ire ] [-href] pattern
    Without opts, pattern is taken as a module name to start browser showing docs for.
    With opt(s):
      -re: pattern is taken as regex to print available matching doc names
      -ire: same as -re but case insensitive
      -href: prints doc href paths along with names found.
      -h: print this
    
Doc info is retrieved from the html file defined by environment name PY_DOC_INDEX,
e.g., modindex.html  and this is located (along with pages therefrom referenced)
by prefixing the string defined by PY_DOC_PREFIX, e.g., D:/Python23/Doc/ (note
forward slashing and ending slash). The ref_name_patt regex may need change if
generated documentation links change format.
"""
__version__ = '0.10a'

# Original code by Bengt Richter, offered for free use, with no warranty of any kind.
# v0.1a: 20030813 13:29:40
#   + docs and untested env variable defs for doc locs
#   + using webbrowser module to start browser instead of os.system

# handy to run from c:\util\modoc.cmd wrapper, e.g.,
# @python c:\pywk\ut\modoc.py %*
import re, os, webbrowser

PY_DOC_PREFIX = os.environ.get('PY_DOC_PREFIX', r'D:/Python23/Doc/')
PY_DOC_INDEX  = os.environ.get('PY_DOC_INDEX',  r'modindex.html')

def dispmod(namex='', **opts):
    """Display module doc via browser or search names for match. See module doc."""
    page = file(PY_DOC_PREFIX+PY_DOC_INDEX).read()
    ref_name_patt = r'<dt><a href="([^"]+)"><tt class="module">([^<]+)' #XXX brittle
    rx = re.compile(ref_name_patt)
    modict = dict([(name, ref) for ref,name in rx.findall(page)])
    names = modict.keys()
    names.sort()
    if opts:
        regex = namex   # default case sensitive match
        if 're' in opts: pass
        elif 'ire' in opts:
            regex = '(?i)'+namex
        elif 'all' in opts:
            regex = None
        if regex:
            rx = re.compile(regex)
            names = list(filter(rx.search, names))
        names.sort()
        for i, name in enumerate(names):
            if 'href' in opts:
                print '%19s: %r' % (name, modict[name])
            else:
                if i and not i%4: print
                print '%-19s' % name,
    else:
        namex = namex.lower()
        for name in names:
            if name.lower() == namex:
                webbrowser.open_new('%s%s' % (PY_DOC_PREFIX, modict[name]))
                return
        raise SystemExit, 'Module "%s" not found.' % namex
        
if __name__ == '__main__':
    import sys
    args = sys.argv[1:]
    if not args or '-h' in args: raise SystemExit, __doc__
    callargs=[]; callkw={}
    while args:
        arg = args.pop(0)
        if arg.startswith('-'):
            callkw[arg[1:]]=True
        else:
            callargs.append(arg)
    dispmod(*callargs, **callkw)
-------------------------------------------------------------------------------------------

Regards,
Bengt Richter