pydoc should be integrated with HTML doc

[gvanrossum]

BPO	405554
Nosy	@gvanrossum, @akuchling

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields: ```python assignee = None closed_at = created_at = labels = ['type-feature', 'library'] title = 'pydoc should be integrated with HTML doc' updated_at = user = 'https://github.com/gvanrossum' ``` bugs.python.org fields: ```python activity = actor = 'akuchling' assignee = 'ping' closed = True closed_date = None closer = None components = ['Library (Lib)'] creation = creator = 'gvanrossum' dependencies = [] files = [] hgrepos = [] issue_num = 405554 keywords = [] message_count = 4.0 messages = ['3665', '3666', '3667', '3668'] nosy_count = 4.0 nosy_names = ['gvanrossum', 'ping', 'akuchling', 'gtk'] pr_nums = [] priority = 'normal' resolution = 'later' stage = None status = 'closed' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue405554' versions = [] ```

[gvanrossum]

I really like pydoc, but it misses one feature compared to perldoc: often the *good* documentation for a module or class is in the library reference manual. There should be a way to get that integrated with the stuff that pydoc extracts from the doc strings.

(Wasn't this Paul Prescod's original idea?)

[9647ba2a-5717-4481-b336-914e78a93294]

Logged In: YES user_id=45338

Although there is now some integration with the reference manual, this issue is still largely unaddressed, since we haven't decided how to present the two kinds of documentation together or whether to merge them somehow.

Leaving this open for now.

[fdc50012-c06d-4cc1-8a5a-4f7229b1cb94]

Logged In: YES user_id=59803

I haven't seen anything in the library reference that couldn't be sucked directly out of the source by some appropriate combination of formally parseable docstrings (PEP-256, PEP-256) and some suitable markup format (structuredtext.sf.net). :)

As a less mind-bending alternative, the docstring processing framework importantly leaves dereferencing links to the caller. If you decide on a standard way of referencing pages in the manual, module authors will need only insert simple links in their docstrings to refer to the [externally maintained] documentation::

Please refer to ftp-objects_ for more detail.

... or::

Please refer to FTP Objects_ for more detail.

.. _FTP Objects: %(ftp-objects)

... or whatever.

Someone, tell me I'm nuts. :)

[akuchling]

Logged In: YES user_id=11375

Added to PEP-42 and closed.