[Python-checkins] cpython (merge 3.2 -> default): Merge doc changes from 3.2 (#10454, #12298)
eric.araujo
python-checkins at python.org
Fri Sep 2 17:45:26 CEST 2011
http://hg.python.org/cpython/rev/892e0ee4ca32
changeset: 72192:892e0ee4ca32
parent: 72190:9526cd63632f
parent: 72191:941106bcd327
user: Éric Araujo <merwok at netwok.org>
date: Fri Sep 02 00:03:20 2011 +0200
summary:
Merge doc changes from 3.2 (#10454, #12298)
files:
Doc/documenting/markup.rst | 5 ++-
Doc/library/functions.rst | 36 ++++++++++++++++-----
Doc/library/stdtypes.rst | 4 ++
Doc/library/string.rst | 2 +
Lib/compileall.py | 14 ++++----
Lib/distutils/tests/support.py | 7 +--
Lib/pipes.py | 2 -
7 files changed, 47 insertions(+), 23 deletions(-)
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -513,7 +513,10 @@
.. describe:: keyword
- The name of a keyword in Python.
+ The name of a Python keyword. Using this role will generate a link to the
+ documentation of the keyword. ``True``, ``False`` and ``None`` do not use
+ this role, but simple code markup (````True````), given that they're
+ fundamental to the language and should be known to any programmer.
.. describe:: mailheader
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -10,7 +10,7 @@
=================== ================= ================== ================ ====================
.. .. Built-in Functions .. ..
=================== ================= ================== ================ ====================
-:func:`abs` :func:`dict` :func:`help` :func:`min` :func:`setattr`
+:func:`abs` |func-dict|_ :func:`help` :func:`min` :func:`setattr`
:func:`all` :func:`dir` :func:`hex` :func:`next` :func:`slice`
:func:`any` :func:`divmod` :func:`id` :func:`object` :func:`sorted`
:func:`ascii` :func:`enumerate` :func:`input` :func:`oct` :func:`staticmethod`
@@ -19,13 +19,22 @@
:func:`bytearray` :func:`filter` :func:`issubclass` :func:`pow` :func:`super`
:func:`bytes` :func:`float` :func:`iter` :func:`print` :func:`tuple`
:func:`callable` :func:`format` :func:`len` :func:`property` :func:`type`
-:func:`chr` :func:`frozenset` :func:`list` :func:`range` :func:`vars`
+:func:`chr` |func-frozenset|_ :func:`list` :func:`range` :func:`vars`
:func:`classmethod` :func:`getattr` :func:`locals` :func:`repr` :func:`zip`
:func:`compile` :func:`globals` :func:`map` :func:`reversed` :func:`__import__`
:func:`complex` :func:`hasattr` :func:`max` :func:`round`
-:func:`delattr` :func:`hash` :func:`memoryview` :func:`set`
+:func:`delattr` :func:`hash` |func-memoryview|_ |func-set|_
=================== ================= ================== ================ ====================
+.. using :func:`dict` would create a link to another page, so local targets are
+ used, with replacement texts to make the output in the table consistent
+
+.. |func-dict| replace:: ``dict()``
+.. |func-frozenset| replace:: ``frozenset()``
+.. |func-memoryview| replace:: ``memoryview()``
+.. |func-set| replace:: ``set()``
+
+
.. function:: abs(x)
Return the absolute value of a number. The argument may be an
@@ -74,11 +83,12 @@
.. function:: bool([x])
- Convert a value to a Boolean, using the standard truth testing procedure. If
- *x* is false or omitted, this returns :const:`False`; otherwise it returns
- :const:`True`. :class:`bool` is also a class, which is a subclass of
- :class:`int`. Class :class:`bool` cannot be subclassed further. Its only
- instances are :const:`False` and :const:`True`.
+ Convert a value to a Boolean, using the standard :ref:`truth testing
+ procedure <truth>`. If *x* is false or omitted, this returns ``False``;
+ otherwise it returns ``True``. :class:`bool` is also a class, which is a
+ subclass of :class:`int` (see :ref:`typesnumeric`). Class :class:`bool`
+ cannot be subclassed further. Its only instances are ``False`` and
+ ``True`` (see :ref:`bltin-boolean-values`).
.. index:: pair: Boolean; type
@@ -248,6 +258,7 @@
example, ``delattr(x, 'foobar')`` is equivalent to ``del x.foobar``.
+.. _func-dict:
.. function:: dict([arg])
:noindex:
@@ -491,6 +502,7 @@
The float type is described in :ref:`typesnumeric`.
+
.. function:: format(value[, format_spec])
.. index::
@@ -511,6 +523,8 @@
:exc:`TypeError` exception is raised if the method is not found or if either
the *format_spec* or the return value are not strings.
+
+.. _func-frozenset:
.. function:: frozenset([iterable])
:noindex:
@@ -717,6 +731,8 @@
such as ``sorted(iterable, key=keyfunc, reverse=True)[0]`` and
``heapq.nlargest(1, iterable, key=keyfunc)``.
+
+.. _func-memoryview:
.. function:: memoryview(obj)
:noindex:
@@ -1040,7 +1056,7 @@
Range objects implement the :class:`collections.Sequence` ABC, and provide
features such as containment tests, element index lookup, slicing and
- support for negative indices:
+ support for negative indices (see :ref:`typesseq`):
>>> r = range(0, 20, 2)
>>> r
@@ -1108,6 +1124,8 @@
can't be represented exactly as a float. See :ref:`tut-fp-issues` for
more information.
+
+.. _func-set:
.. function:: set([iterable])
:noindex:
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2724,6 +2724,8 @@
It is written as ``Ellipsis`` or ``...``.
+.. _bltin-notimplemented-object:
+
The NotImplemented Object
-------------------------
@@ -2735,6 +2737,8 @@
It is written as ``NotImplemented``.
+.. _bltin-boolean-values:
+
Boolean Values
--------------
diff --git a/Doc/library/string.rst b/Doc/library/string.rst
--- a/Doc/library/string.rst
+++ b/Doc/library/string.rst
@@ -216,6 +216,8 @@
it refers to a named keyword argument. If the numerical arg_names in a format string
are 0, 1, 2, ... in sequence, they can all be omitted (not just some)
and the numbers 0, 1, 2, ... will be automatically inserted in that order.
+Because *arg_name* is not quote-delimited, it is not possible to specify arbitrary
+dictionary keys (e.g., the strings ``'10'`` or ``':-]'``) within a format string.
The *arg_name* can be followed by any number of index or
attribute expressions. An expression of the form ``'.name'`` selects the named
attribute using :func:`getattr`, while an expression of the form ``'[index]'``
diff --git a/Lib/compileall.py b/Lib/compileall.py
--- a/Lib/compileall.py
+++ b/Lib/compileall.py
@@ -142,7 +142,7 @@
Arguments (all optional):
- skip_curdir: if true, skip current directory (default true)
+ skip_curdir: if true, skip current directory (default True)
maxlevels: max recursion level (default 0)
force: as for compile_dir() (default False)
quiet: as for compile_dir() (default False)
@@ -177,17 +177,17 @@
help='use legacy (pre-PEP3147) compiled file locations')
parser.add_argument('-d', metavar='DESTDIR', dest='ddir', default=None,
help=('directory to prepend to file paths for use in '
- 'compile time tracebacks and in runtime '
+ 'compile-time tracebacks and in runtime '
'tracebacks in cases where the source file is '
'unavailable'))
parser.add_argument('-x', metavar='REGEXP', dest='rx', default=None,
- help=('skip files matching the regular expression. '
- 'The regexp is searched for in the full path '
- 'to each file considered for compilation.'))
+ help=('skip files matching the regular expression; '
+ 'the regexp is searched for in the full path '
+ 'of each file considered for compilation'))
parser.add_argument('-i', metavar='FILE', dest='flist',
help=('add all the files and directories listed in '
- 'FILE to the list considered for compilation. '
- 'If "-", names are read from stdin.'))
+ 'FILE to the list considered for compilation; '
+ 'if "-", names are read from stdin'))
parser.add_argument('compile_dest', metavar='FILE|DIR', nargs='*',
help=('zero or more file and directory names '
'to compile; if no arguments given, defaults '
diff --git a/Lib/distutils/tests/support.py b/Lib/distutils/tests/support.py
--- a/Lib/distutils/tests/support.py
+++ b/Lib/distutils/tests/support.py
@@ -175,10 +175,9 @@
def fixup_build_ext(cmd):
"""Function needed to make build_ext tests pass.
- When Python was build with --enable-shared on Unix, -L. is not good
- enough to find the libpython<blah>.so. This is because regrtest runs
- it under a tempdir, not in the top level where the .so lives. By the
- time we've gotten here, Python's already been chdir'd to the tempdir.
+ When Python was built with --enable-shared on Unix, -L. is not enough to
+ find libpython<blah>.so, because regrtest runs in a tempdir, not in the
+ source directory where the .so lives.
When Python was built with in debug mode on Windows, build_ext commands
need their debug attribute set, and it is not done automatically for
diff --git a/Lib/pipes.py b/Lib/pipes.py
--- a/Lib/pipes.py
+++ b/Lib/pipes.py
@@ -54,8 +54,6 @@
To create a new template object initialized to a given one:
t2 = t.clone()
-
-For an example, see the function test() at the end of the file.
""" # '
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list