[Python-Dev] Checked in...

[Ka-Ping Yee]

On Mon, 17 Jul 2000, Paul Prescod wrote:
> Ka-Ping Yee wrote:
> > My plan was to complete htmldoc.py and try to get in into the
> > distribution so that anyone could browse documentation on the
> > standard library.  
> 
> +1

Yay. :)

> > It would include an option to start a little
> > webserver with a one-line command so that doc pages could be
> > automatically generated on your own modules as you work on them.
> 
> +0

I'd like Python to come packaged in such a way that people can
easily deploy it in an organization along with whatever stuff
they develop.  So being able to very easily generate and see docs
on their own modules, integrated with the view of docs for the
rest of the standard library, would be a nice thing.  It makes a
Python environment easier to support.

> > The next step in the plan was to provide text output so you
> > could ask about modules from the shell prompt (like a "man"
> > command specific to Python) and a function call you could use
> > from inside the interpreter to get quick help as well.
> 
> Not sure how to interpret this. If it depends on the aforementioned web
> server, I'm -1. If it calls the htmldoc code directly, I'm +1.

Did you mean you wanted it to generate HTML and then use htmllib,
like you did, to turn it into text?  I hadn't thought of that.

The way i imagined it, it wouldn't depend on htmldoc or the web
server at all.  It would call inspect.py to get its info and just
format some text on its own.

Before you posted onlineHelp (great work, by the way!), i was
thinking of calling it "pydoc", and envisioning something like:

    >>> import pydoc               # or have site.py take care of this
    >>> pydoc.doc(urllib)
    ---- module urllib:
    Open an arbitrary URL.

    See the following document for more info on URLs:
    "Names and Addresses, URIs, URLs, URNs, URCs", at
    http://www.w3.org/pub/WWW/Addressing/Overview.html
    .
    .
    .
    ---- functions:
    urlopen(url, data=None)

    urlretrieve(url, filename=None, reporthook=Nne)
    .
    .
    .
    ---- classes:
    class URLopener:
        Class to open URLs.
        .
        .
        .
    etc.

and also the same output from the shell command

    % pydoc urllib
    ---- module urllib:
    Open an arbitrary URL.

    See the following document for more info on URLs:
    "Names and Addresses, URIs, URLs, URNs, URCs", at
    http://www.w3.org/pub/WWW/Addressing/Overview.html
    .
    .
    .
    etc.

This is basically identical to how you were describing the
onlinehelp/help commands.  I didn't think of using the external
(TeX/HTML) documentation though... that's a clever idea.  So:
    
    - use doc pages only?
    
    - use internal info only?

    - separate scripts for each?

    - use both?

    - use doc pages if installed, then fall back to internal info?


One other note: how about leaving the job of listing the text to
to an external app like "less"/"more", as determined by the PAGER
environment variable, allowing customization?  The code we use to
figure out what program to run should eventually move into
launch.textviewer.

Perhaps this would then provide interactive apps (e.g. IDLE) the
opportunity to simply replace (or hook into) launch.textviewer.

> I'd love
> to have the interpreter build on your docstring-formatting heuristics
> and that docstring-language plugin feature we discussed to allow people
> to experiment with semi-structured docstring formats.

Sure.  Not a high priority for me, but once we have the module,
it's easy to extend and experiment.


-- ?!ng