From a47bbf5a4b6aaba52be774ddd2cb23be26a638ef Mon Sep 17 00:00:00 2001 From: Alexander Belopolsky Date: Thu, 18 Nov 2010 01:52:54 +0000 Subject: [PATCH] Issue #10446: Several changes to module documentation generated by pydoc: 1. Online reference manual link is now version-specific and the 'MODULE DOCS' section renamed to 'MODULE REFERENCE'. 2. 'FILE' section is moved to the end of the file. 3. Special names processed by pydoc such as __version__ or __credits__ are now excluded from the DATA section. 4. Defined __all__ to prevent pydoc from exposing undocumented details about itself. 5. Removed Python 2.3 compatibility code. --- Doc/library/pydoc.rst | 8 +++--- Lib/pydoc.py | 55 +++++++++++++++++++++--------------------- Lib/test/pydoc_mod.py | 2 +- Lib/test/test_pydoc.py | 16 +++++------- 4 files changed, 39 insertions(+), 42 deletions(-) diff --git a/Doc/library/pydoc.rst b/Doc/library/pydoc.rst index 4103dd4d633..cbb8af851e8 100644 --- a/Doc/library/pydoc.rst +++ b/Doc/library/pydoc.rst @@ -63,7 +63,9 @@ documents precisely the version of the module you would get if you started the Python interpreter and typed ``import spam``. Module docs for core modules are assumed to reside in -http://docs.python.org/library/. This can be overridden by setting the -:envvar:`PYTHONDOCS` environment variable to a different URL or to a local -directory containing the Library Reference Manual pages. +``http://docs.python.org/X.Y/library/`` where ``X`` and ``Y`` are the +major and minor version numbers of the Python interpreter. This can +be overridden by setting the :envvar:`PYTHONDOCS` environment variable +to a different URL or to a local directory containing the Library +Reference Manual pages. diff --git a/Lib/pydoc.py b/Lib/pydoc.py index 5e54468f4e8..9ede259cdd9 100755 --- a/Lib/pydoc.py +++ b/Lib/pydoc.py @@ -26,13 +26,13 @@ to a file named ".html". Module docs for core modules are assumed to be in - http://docs.python.org/library/ + http://docs.python.org/X.Y/library/ This can be overridden by setting the PYTHONDOCS environment variable to a different URL or to a local directory containing the Library Reference Manual pages. """ - +__all__ = ['help'] __author__ = "Ka-Ping Yee " __date__ = "26 February 2001" @@ -54,14 +54,7 @@ Richard Chamberlain, for the first implementation of textdoc. import sys, imp, os, re, inspect, builtins, pkgutil from reprlib import Repr from traceback import extract_tb as _extract_tb -try: - from collections import deque -except ImportError: - # Python 2.3 compatibility - class deque(list): - def popleft(self): - return self.pop(0) - +from collections import deque # --------------------------------------------------------- common routines def pathdirs(): @@ -159,7 +152,8 @@ def visiblename(name, all=None): # Certain special names are redundant. _hidden_names = ('__builtins__', '__doc__', '__file__', '__path__', '__module__', '__name__', '__slots__', '__package__', - '__cached__') + '__cached__', '__author__', '__credits__', '__date__', + '__version__') if name in _hidden_names: return 0 # Private names are hidden, but special names are displayed. if name.startswith('__') and name.endswith('__'): return 1 @@ -306,6 +300,11 @@ def safeimport(path, forceload=0, cache={}): # ---------------------------------------------------- formatter base class class Doc: + + PYTHONDOCS = os.environ.get("PYTHONDOCS", + "http://docs.python.org/%d.%d/library" + % sys.version_info[:2]) + def document(self, object, name=None, *args): """Generate documentation for an object.""" args = (object, name) + args @@ -340,10 +339,10 @@ class Doc: except TypeError: file = '(built-in)' - docloc = os.environ.get("PYTHONDOCS", - "http://docs.python.org/library") + docloc = os.environ.get("PYTHONDOCS", self.PYTHONDOCS) + basedir = os.path.join(sys.exec_prefix, "lib", - "python"+sys.version[0:3]) + "python%d.%d" % sys.version_info[:2]) if (isinstance(object, type(os)) and (object.__name__ in ('errno', 'exceptions', 'gc', 'imp', 'marshal', 'posix', 'signal', 'sys', @@ -607,7 +606,7 @@ class HTMLDoc(Doc): head = head + ' (%s)' % ', '.join(info) docloc = self.getdocloc(object) if docloc is not None: - docloc = '
Module Docs' % locals() + docloc = '
Module Reference' % locals() else: docloc = '' result = self.heading( @@ -1016,21 +1015,16 @@ class TextDoc(Doc): name = object.__name__ # ignore the passed-in name synop, desc = splitdoc(getdoc(object)) result = self.section('NAME', name + (synop and ' - ' + synop)) - - try: - all = object.__all__ - except AttributeError: - all = None - - try: - file = inspect.getabsfile(object) - except TypeError: - file = '(built-in)' - result = result + self.section('FILE', file) - + all = getattr(object, '__all__', None) docloc = self.getdocloc(object) if docloc is not None: - result = result + self.section('MODULE DOCS', docloc) + result = result + self.section('MODULE REFERENCE', docloc + """ + +The following documentation is automatically generated from the Python source +files. It may be incomplete, incorrect or include features that are considered +implementation detail and may vary between Python implementations. When in +doubt, consult the module reference at the location listed above. +""") if desc: result = result + self.section('DESCRIPTION', desc) @@ -1109,6 +1103,11 @@ class TextDoc(Doc): result = result + self.section('AUTHOR', str(object.__author__)) if hasattr(object, '__credits__'): result = result + self.section('CREDITS', str(object.__credits__)) + try: + file = inspect.getabsfile(object) + except TypeError: + file = '(built-in)' + result = result + self.section('FILE', file) return result def docclass(self, object, name=None, mod=None): diff --git a/Lib/test/pydoc_mod.py b/Lib/test/pydoc_mod.py index 9c53324a6d5..f86b5c621e3 100644 --- a/Lib/test/pydoc_mod.py +++ b/Lib/test/pydoc_mod.py @@ -3,7 +3,7 @@ __author__ = "Benjamin Peterson" __credits__ = "Nobody" __version__ = "1.2.3.4" - +__xyz__ = "X, Y and Z" class A: """Hello and goodbye""" diff --git a/Lib/test/test_pydoc.py b/Lib/test/test_pydoc.py index 603755ad0ee..af28348b8d0 100644 --- a/Lib/test/test_pydoc.py +++ b/Lib/test/test_pydoc.py @@ -22,9 +22,6 @@ if hasattr(pydoc_mod, "__loader__"): expected_text_pattern = """ NAME test.pydoc_mod - This is a test module for test_pydoc - -FILE - %s %s CLASSES builtins.object @@ -72,9 +69,7 @@ FUNCTIONS nodoc_func() DATA - __author__ = 'Benjamin Peterson' - __credits__ = 'Nobody' - __version__ = '1.2.3.4' + __xyz__ = 'X, Y and Z' VERSION 1.2.3.4 @@ -84,6 +79,9 @@ AUTHOR CREDITS Nobody + +FILE + %s """.strip() expected_html_pattern = """ @@ -167,9 +165,7 @@ war Data \x20\x20\x20\x20         -__author__ = 'Benjamin Peterson'
-__credits__ = 'Nobody'
-__version__ = '1.2.3.4'

+__xyz__ = 'X, Y and Z'

 
@@ -259,7 +255,7 @@ class PyDocDocTest(unittest.TestCase): def test_text_doc(self): result, doc_loc = get_pydoc_text(pydoc_mod) expected_text = expected_text_pattern % \ - (inspect.getabsfile(pydoc_mod), doc_loc) + (doc_loc, inspect.getabsfile(pydoc_mod)) if result != expected_text: print_diffs(expected_text, result) self.fail("outputs are not equal, see diff above")