[Python-checkins] r86505 - in python/branches/release31-maint: Doc/library/pydoc.rst Lib/pydoc.py Lib/test/pydoc_mod.py Lib/test/test_pydoc.py
alexander.belopolsky
python-checkins at python.org
Thu Nov 18 02:58:16 CET 2010
Author: alexander.belopolsky
Date: Thu Nov 18 02:58:16 2010
New Revision: 86505
Log:
Merged revisions 86504 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r86504 | alexander.belopolsky | 2010-11-17 20:52:54 -0500 (Wed, 17 Nov 2010) | 15 lines
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.
........
Modified:
python/branches/release31-maint/ (props changed)
python/branches/release31-maint/Doc/library/pydoc.rst
python/branches/release31-maint/Lib/pydoc.py
python/branches/release31-maint/Lib/test/pydoc_mod.py
python/branches/release31-maint/Lib/test/test_pydoc.py
Modified: python/branches/release31-maint/Doc/library/pydoc.rst
==============================================================================
--- python/branches/release31-maint/Doc/library/pydoc.rst (original)
+++ python/branches/release31-maint/Doc/library/pydoc.rst Thu Nov 18 02:58:16 2010
@@ -64,7 +64,9 @@
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.
Modified: python/branches/release31-maint/Lib/pydoc.py
==============================================================================
--- python/branches/release31-maint/Lib/pydoc.py (original)
+++ python/branches/release31-maint/Lib/pydoc.py Thu Nov 18 02:58:16 2010
@@ -27,13 +27,13 @@
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 <ping at lfw.org>"
__date__ = "26 February 2001"
@@ -55,14 +55,7 @@
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 @@
"""Decide whether to show documentation on a variable."""
# Certain special names are redundant.
_hidden_names = ('__builtins__', '__doc__', '__file__', '__path__',
- '__module__', '__name__', '__slots__', '__package__')
+ '__module__', '__name__', '__slots__', '__package__',
+ '__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 @@
# ---------------------------------------------------- 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 @@
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 @@
head = head + ' (%s)' % ', '.join(info)
docloc = self.getdocloc(object)
if docloc is not None:
- docloc = '<br><a href="%(docloc)s">Module Docs</a>' % locals()
+ docloc = '<br><a href="%(docloc)s">Module Reference</a>' % locals()
else:
docloc = ''
result = self.heading(
@@ -1016,21 +1015,16 @@
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 @@
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):
Modified: python/branches/release31-maint/Lib/test/pydoc_mod.py
==============================================================================
--- python/branches/release31-maint/Lib/test/pydoc_mod.py (original)
+++ python/branches/release31-maint/Lib/test/pydoc_mod.py Thu Nov 18 02:58:16 2010
@@ -3,7 +3,7 @@
__author__ = "Benjamin Peterson"
__credits__ = "Nobody"
__version__ = "1.2.3.4"
-
+__xyz__ = "X, Y and Z"
class A:
"""Hello and goodbye"""
Modified: python/branches/release31-maint/Lib/test/test_pydoc.py
==============================================================================
--- python/branches/release31-maint/Lib/test/test_pydoc.py (original)
+++ python/branches/release31-maint/Lib/test/test_pydoc.py Thu Nov 18 02:58:16 2010
@@ -18,9 +18,6 @@
"""
NAME
test.pydoc_mod - This is a test module for test_pydoc
-
-FILE
- %s
%s
CLASSES
builtins.object
@@ -68,9 +65,7 @@
nodoc_func()
DATA
- __author__ = 'Benjamin Peterson'
- __credits__ = 'Nobody'
- __version__ = '1.2.3.4'
+ __xyz__ = 'X, Y and Z'
VERSION
1.2.3.4
@@ -80,6 +75,9 @@
CREDITS
Nobody
+
+FILE
+ %s
""".strip()
expected_html_pattern = \
@@ -164,9 +162,7 @@
<font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
\x20\x20\x20\x20
<tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td>
-<td width="100%%"><strong>__author__</strong> = 'Benjamin Peterson'<br>
-<strong>__credits__</strong> = 'Nobody'<br>
-<strong>__version__</strong> = '1.2.3.4'</td></tr></table><p>
+<td width="100%%"><strong>__xyz__</strong> = 'X, Y and Z'</td></tr></table><p>
<table width="100%%" cellspacing=0 cellpadding=2 border=0 summary="section">
<tr bgcolor="#7799ee">
<td colspan=3 valign=bottom> <br>
@@ -249,7 +245,7 @@
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")
More information about the Python-checkins
mailing list