[Doc-SIG] [Python-Dev] Finishing up PEP 3108

[Steve Holden]

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/