[Python-Dev] pydoc II

[Laurent Gautier]

2007/3/11, Gustavo Carneiro <gjcarneiro at gmail.com>:
> On 3/11/07, Laurent Gautier <lgautier at gmail.com> wrote:
> [...]
> > A prototype is being worked on, and I have been looking at code and/or
> > functionalities in pydoc, epydoc, pydoctor, and ipython (for the
> > interactive console), and there a lot of nice things in all these
> > efforts. The name of the game is now to have something that likely to
> > offer the best of all (although it can be an easy way to get no one
> > happy in the end).
> >
> > Hopefully someone kept reading up to here...
> >
> > Some of the key points so far:
> >
> > library:
> > - ability to browse documentation inside module/package files without
> > loading them
>
>   Most importantly, we also need the reserve: ability to attach external
> documentation to modules/packages without increasing their size.

I suspect that this will sparkle a long thread about python documentation
system, but I will comment nevertheless while trying to avoid being caught
in the middle.
Well this sort of thing is technically feasible, and when I am looking solely at
pydoc the deal for me is how can it be made easily and as little hackish as
possible.

>   For instance, one of the reasons no one ever bothered to add pydoc
> documentation to PyGTK (beyond a few docstrings that can be generated in
> runtime) is that the entire documentation for PyGTK would be far too large
> to place directly into the module readonly data segment.
>
>   Documentation should be able to live in another file, separate from the
> module source code, and loaded on demand.  Loading the pydoc file should be
> preferably done through read-only memory mapping a file.

Well, that's an interesting idea... and the structure we start having could
see something along those lines implemented. Being something non-standard
for the time being, that would be something that the maintainer of the module
having that particular request would take care of.
(the deal with pydoc would be to make plugging that in easy)
Instructions to use that "other-documentation" through pydoc could be included
in the top-level docstring for the pygtk module for example... how
does this sound ?


L.


> --
> Gustavo J. A. M. Carneiro
> "The universe is always one step beyond logic."