[Python-Dev] Checked in...

[Paul Prescod]

Ka-Ping Yee wrote:
> 
> ...
> 
> 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.

Agreed. I'm just not sure if it requires a webserver. You could set up a
makefile to recognize when an HTML doc is out of sync with its Python.

> 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.

I didn't know about the clean separation of htmldoc and inspect when I
wrote that. You're right, it should call inspect directly.

> 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?

That's not doable unless there is a process to get docstrings into doc
pages -- which is a great idea but probably some ways away.

>     - use internal info only?

Where do I get information on statements and "topics" (like slicing, as
a topic).

>     - separate scripts for each?

Maybe internally. Ideally not at the user interface layer.

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

My model, which you may or may not have noticed yet, is to use
docstrings for objects that have docstrings, but the docstrings can
point to HTML documentation in the circumstance where the canonical doc
is maintained in HTML. In that case, I magically go to the HTML, rather
than showing the reference.

My personal feeling is that over time a lot of the library documentation
should move inline for ease of maintenance and reduction of duplication.
But that won't happen until we integrate inspect.py and latex2html. 

I have some ideas about that too. It's the opposite of the current
scheme. We should put pointers from the LaTeX into the modules. A
preprocessor would use inspect.py to generate a combined LaTeX that
merges inline (LaTeX) and out-of-line (docstring) information. Then we
start moving bits of the documentation into docstrings a little at a
time. Anything that uses LaTeX features that are "funky" can stay in
LaTeX until we invent a structured docstring syntax (whenever).

> 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.

I'm happy to do this on platforms that support it. I'm somewhat nervous
about popen on non-Unix systems...maybe I should write a text file and
then launch the pager on that.

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

Good idea. One tricky issue is what format to use, though. troff/man is
great for Unix TTY, HTML is great for GUIs and raw text is the lowest
common denominiator. Do I want to get into n*m translations? Maybe,
maybe not. Or maybe HTML is the lowest common denominator and Unix TTY
users should use lynx?

-- 
 Paul Prescod - Not encumbered by corporate consensus
It's difficult to extract sense from strings, but they're the only
communication coin we can count on. 
	- http://www.cs.yale.edu/~perlis-alan/quotes.html