[Doc-SIG] [Python-Dev] Finishing up PEP 3108
Steve Holden
steve at holdenweb.com
Sat May 31 17:42:24 CEST 2008
Georg Brandl wrote:
> Brett Cannon schrieb:
>
>>>> Issue 2873 - htmllib is slated to go, but pydoc still uses it. Then
>>>> again, pydoc is busted thanks to the new doc format.
>>>
>>> I will try to handle this in the coming week.
>>>
>>
>> Fred had the interesting suggestion of removing pydoc in Py3K based on
>> the thinking that documentation tools like pydoc should be external to
>> Python. With the docs now so easy to generate directly, should pydoc
>> perhaps just be gutted to only what is needed for help() to work?
>
> pydoc is fine for displaying docstring help, and interactive help.
> This should stay.
>
> Of course, it would also be nice for ``help("if")`` to work effortlessly,
> which it currently only does if the generated HTML documentation is
> available somewhere, which it typically isn't -- on Unix most distributions
> put it in a separate package (from which pydoc won't always find it
> of its own), on Windows only the CHM file is distributed and must be
> decompiled to get single HTML files.
>
> Now that the docs are reST, the source is almost pretty enough to display
> it raw, but I could also imagine a "text" writer that removes the more
> obscure markup to present a casual-reader-friendly text version.
>
> The needed sources could then be distributed with Python -- it shouldn't
> be more than about 200 kb.
The versioned documentation will sometimes be available from the
Internet if you want to think about using that as a fallback source. It
*would* be nice if help("if") worked.
It would be even handier if help(if) worked, but that's a syntax
problem, and it would be a horrendous one to overcome, I suspect.
regards
Steve
--
Steve Holden +1 571 484 6266 +1 800 494 3119
Holden Web LLC http://www.holdenweb.com/
More information about the Doc-SIG
mailing list