Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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.
........
This commit is contained in:
Alexander Belopolsky 2010-11-18 01:58:16 +00:00
parent 6083170858
commit 4979b9b91e
4 changed files with 39 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Doc/library/pydoc.rst
View File

@ -64,7 +64,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.

55
Lib/pydoc.py
View File

@ -27,13 +27,13 @@ to a file named "<name>.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 <ping@lfw.org>"
__date__ = "26 February 2001"
@ -55,14 +55,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):
"""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 @@ 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 = '<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 @@ 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):

2
Lib/test/pydoc_mod.py
View File

@ -3,7 +3,7 @@
__author__ = "Benjamin Peterson"
__credits__ = "Nobody"
__version__ = "1.2.3.4"
__xyz__ = "X, Y and Z"
class A:
"""Hello and goodbye"""

16
Lib/test/test_pydoc.py
View File

@ -18,9 +18,6 @@ expected_text_pattern = \
"""
NAME
test.pydoc_mod - This is a test module for test_pydoc
FILE
%s
%s
CLASSES
builtins.object
@ -68,9 +65,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
@ -80,6 +75,9 @@ AUTHOR
CREDITS
Nobody
FILE
%s
""".strip()
expected_html_pattern = \
@ -164,9 +162,7 @@ war</tt></dd></dl>
<font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
\x20\x20\x20\x20
<tr><td bgcolor="#55aa55"><tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</tt></td><td>&nbsp;</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>&nbsp;<br>
@ -249,7 +245,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")