Re: [Python-Dev] Finishing up PEP 3108

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view
|

Re: [Python-Dev] Finishing up PEP 3108

Steve Holden-5
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/

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig