[Python-checkins] cpython (merge 3.2 -> default): Merge doc fixes from 3.2
eric.araujo
python-checkins at python.org
Thu Jun 9 16:45:13 CEST 2011
http://hg.python.org/cpython/rev/6feb5c87a7fb
changeset: 70735:6feb5c87a7fb
parent: 70733:af7bc95e5b1e
parent: 70730:42cd9776017d
user: Éric Araujo <merwok at netwok.org>
date: Thu Jun 09 16:28:19 2011 +0200
summary:
Merge doc fixes from 3.2
files:
Doc/c-api/intro.rst | 4 ++--
Doc/distutils/install.rst | 15 +++++++++------
Doc/distutils/introduction.rst | 10 ++++++++--
Doc/documenting/markup.rst | 11 ++++++-----
Doc/library/builtins.rst | 4 +++-
Doc/library/constants.rst | 2 ++
Doc/license.rst | 4 ++--
Doc/using/cmdline.rst | 2 +-
8 files changed, 33 insertions(+), 19 deletions(-)
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -588,8 +588,8 @@
Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces
what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
-enabled in the Unix build by adding :option:`--with-pydebug` to the
-:file:`configure` command. It is also implied by the presence of the
+enabled in the Unix build by adding ``--with-pydebug`` to the
+:file:`./configure` command. It is also implied by the presence of the
not-Python-specific :c:macro:`_DEBUG` macro. When :c:macro:`Py_DEBUG` is enabled
in the Unix build, compiler optimization is disabled.
diff --git a/Doc/distutils/install.rst b/Doc/distutils/install.rst
--- a/Doc/distutils/install.rst
+++ b/Doc/distutils/install.rst
@@ -96,10 +96,16 @@
directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the
distribution will contain a setup script :file:`setup.py`, and a file named
:file:`README.txt` or possibly just :file:`README`, which should explain that
-building and installing the module distribution is a simple matter of running ::
+building and installing the module distribution is a simple matter of running
+one command from a terminal::
python setup.py install
+For Windows, this command should be run from a command prompt windows ("DOS
+box")::
+
+ setup.py install
+
If all these things are true, then you already know how to build and install the
modules you've just downloaded: Run the command above. Unless you need to
install things in a non-standard way or customize the build process, you don't
@@ -113,14 +119,11 @@
==========================
As described in section :ref:`inst-new-standard`, building and installing a module
-distribution using the Distutils is usually one simple command::
+distribution using the Distutils is usually one simple command to run from a
+terminal::
python setup.py install
-On Unix, you'd run this command from a shell prompt; on Windows, you have to
-open a command prompt window ("DOS box") and do it there; on Mac OS X, you open
-a :command:`Terminal` window to get a shell prompt.
-
.. _inst-platform-variations:
diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst
--- a/Doc/distutils/introduction.rst
+++ b/Doc/distutils/introduction.rst
@@ -79,11 +79,17 @@
for an example)
To create a source distribution for this module, you would create a setup
-script, :file:`setup.py`, containing the above code, and run::
+script, :file:`setup.py`, containing the above code, and run this command from a
+terminal::
python setup.py sdist
-which will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
+For Windows, open a command prompt windows ("DOS box") and change the command
+to::
+
+ setup.py sdist
+
+:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
will unpack into a directory :file:`foo-1.0`.
diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -98,11 +98,12 @@
Spam or ham the foo.
-The signatures of object methods or data attributes should always include the
-type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
-context which type they belong to; this is to enable consistent
-cross-references. If you describe methods belonging to an abstract protocol,
-such as "context managers", include a (pseudo-)type name too to make the
+The signatures of object methods or data attributes should not include the
+class name, but be nested in a class directive. The generated files will
+reflect this nesting, and the target identifiers (for HTML output) will use
+both the class and method name, to enable consistent cross-references. If you
+describe methods belonging to an abstract protocol such as context managers,
+use a class directive with a (pseudo-)type name too to make the
index entries more informative.
The directives are:
diff --git a/Doc/library/builtins.rst b/Doc/library/builtins.rst
--- a/Doc/library/builtins.rst
+++ b/Doc/library/builtins.rst
@@ -7,7 +7,9 @@
This module provides direct access to all 'built-in' identifiers of Python; for
example, ``builtins.open`` is the full name for the built-in function
-:func:`open`.
+:func:`open`. See :ref:`built-in-funcs` and :ref:`built-in-consts` for
+documentation.
+
This module is not normally accessed explicitly by most applications, but can be
useful in modules that provide objects with the same name as a built-in value,
diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst
--- a/Doc/library/constants.rst
+++ b/Doc/library/constants.rst
@@ -1,3 +1,5 @@
+.. _built-in-consts:
+
Built-in Constants
==================
diff --git a/Doc/license.rst b/Doc/license.rst
--- a/Doc/license.rst
+++ b/Doc/license.rst
@@ -847,7 +847,7 @@
-----
The :mod:`pyexpat` extension is built using an included copy of the expat
-sources unless the build is configured :option:`--with-system-expat`::
+sources unless the build is configured ``--with-system-expat``::
Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd
and Clark Cooper
@@ -876,7 +876,7 @@
------
The :mod:`_ctypes` extension is built using an included copy of the libffi
-sources unless the build is configured :option:`--with-system-libffi`::
+sources unless the build is configured ``--with-system-libffi``::
Copyright (c) 1996-2008 Red Hat, Inc and others.
diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst
--- a/Doc/using/cmdline.rst
+++ b/Doc/using/cmdline.rst
@@ -511,7 +511,7 @@
~~~~~~~~~~~~~~~~~~~~
Setting these variables only has an effect in a debug build of Python, that is,
-if Python was configured with the :option:`--with-pydebug` build option.
+if Python was configured with the ``--with-pydebug`` build option.
.. envvar:: PYTHONTHREADDEBUG
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list