[docs] Improve cross-references in pickle documentation (issue 19196)

[storchaka at gmail.com]

Reviewers: Georg,


http://bugs.python.org/review/19196/diff/9476/Doc/distutils/setupscript.rst
File Doc/distutils/setupscript.rst (right):

http://bugs.python.org/review/19196/diff/9476/Doc/distutils/setupscript.rst#newcode149
Doc/distutils/setupscript.rst:149: The
:class:`~distutils.core.Extension` class can be imported from
:mod:`distutils.core` along
On 2013/10/08 22:25:09, Georg wrote:
> unneeded... etc.

Perhaps left one link per subsection?



Please review this at http://bugs.python.org/review/19196/

Affected files:
  Doc/distutils/apiref.rst
  Doc/distutils/extending.rst
  Doc/distutils/setupscript.rst


diff -r a49d313a28ae Doc/distutils/apiref.rst
--- a/Doc/distutils/apiref.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/distutils/apiref.rst	Tue Oct 08 22:58:19 2013 +0300
@@ -994,12 +994,12 @@
    simply the list of all files under *src*, with the names changed to be under
    *dst*.
 
-   *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in
+   *preserve_mode* and *preserve_times* are the same as for :func:`~distutils.file_util.copy_file` in
    :mod:`distutils.file_util`; note that they only apply to regular files, not to
    directories.  If *preserve_symlinks* is true, symlinks will be copied as
    symlinks (on platforms that support them!); otherwise (the default), the
    destination of the symlink will be copied.  *update* and *verbose* are the same
-   as for :func:`copy_file`.
+   as for :func:`~distutils.file_util.copy_file`.
 
    Files in *src* that begin with :file:`.nfs` are skipped (more information on
    these files is available in answer D2 of the `NFS FAQ page
@@ -1175,7 +1175,7 @@
    Generate a useful error message from an :exc:`OSError` exception object.
    Handles Python 1.5.1 and later styles, and does what it can to deal with
    exception objects that don't have a filename (which happens when the error
-   is due to a two-file operation, such as :func:`rename` or :func:`link`).
+   is due to a two-file operation, such as :func:`~os.rename` or :func:`~os.link`).
    Returns the error message as a string prefixed with *prefix*.
 
 
@@ -1265,7 +1265,7 @@
               built/installed/distributed
 
 
-This module provides the :class:`Distribution` class, which represents the
+This module provides the :class:`~distutils.core.Distribution` class, which represents the
 module distribution being built/installed/distributed.
 
 
@@ -1712,7 +1712,7 @@
    options, is the :meth:`run` method, which must also be implemented by every
    command class.
 
-   The class constructor takes a single argument *dist*, a :class:`Distribution`
+   The class constructor takes a single argument *dist*, a :class:`~distutils.core.Distribution`
    instance.
 
 
diff -r a49d313a28ae Doc/distutils/extending.rst
--- a/Doc/distutils/extending.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/distutils/extending.rst	Tue Oct 08 22:58:19 2013 +0300
@@ -17,9 +17,9 @@
 
 Most distutils command implementations are subclasses of the
 :class:`distutils.cmd.Command` class.  New commands may directly inherit from
-:class:`Command`, while replacements often derive from :class:`Command`
+:class:`~distutils.cmd.Command`, while replacements often derive from :class:`~distutils.cmd.Command`
 indirectly, directly subclassing the command they are replacing.  Commands are
-required to derive from :class:`Command`.
+required to derive from :class:`~distutils.cmd.Command`.
 
 .. % \section{Extending existing commands}
 .. % \label{extend-existing}
diff -r a49d313a28ae Doc/distutils/setupscript.rst
--- a/Doc/distutils/setupscript.rst	Tue Oct 08 21:08:48 2013 +0300
+++ b/Doc/distutils/setupscript.rst	Tue Oct 08 22:58:19 2013 +0300
@@ -139,14 +139,14 @@
 
 All of this is done through another keyword argument to :func:`setup`, the
 :option:`ext_modules` option.  :option:`ext_modules` is just a list of
-:class:`Extension` instances, each of which describes a single extension module.
+:class:`~distutils.core.Extension` instances, each of which describes a single extension module.
 Suppose your distribution includes a single extension, called :mod:`foo` and
 implemented by :file:`foo.c`.  If no additional instructions to the
 compiler/linker are needed, describing this extension is quite simple::
 
     Extension('foo', ['foo.c'])
 
-The :class:`Extension` class can be imported from :mod:`distutils.core` along
+The :class:`~distutils.core.Extension` class can be imported from :mod:`distutils.core` along
 with :func:`setup`.  Thus, the setup script for a module distribution that
 contains only this one extension and nothing else might be::
 
@@ -156,7 +156,7 @@
           ext_modules=[Extension('foo', ['foo.c'])],
           )
 
-The :class:`Extension` class (actually, the underlying extension-building
+The :class:`~distutils.core.Extension` class (actually, the underlying extension-building
 machinery implemented by the :command:`build_ext` command) supports a great deal
 of flexibility in describing Python extensions, which is explained in the
 following sections.
@@ -165,7 +165,7 @@
 Extension names and packages
 ----------------------------
 
-The first argument to the :class:`Extension` constructor is always the name of
+The first argument to the :class:`~distutils.core.Extension` constructor is always the name of
 the extension, including any package names.  For example, ::
 
     Extension('foo', ['src/foo1.c', 'src/foo2.c'])
@@ -196,7 +196,7 @@
 Extension source files
 ----------------------
 
-The second argument to the :class:`Extension` constructor is a list of source
+The second argument to the :class:`~distutils.core.Extension` constructor is a list of source
 files.  Since the Distutils currently only support C, C++, and Objective-C
 extensions, these are normally C/C++/Objective-C source files.  (Be sure to use
 appropriate extensions to distinguish C++\ source files: :file:`.cc` and
@@ -232,7 +232,7 @@
 Preprocessor options
 --------------------
 
-Three optional arguments to :class:`Extension` will help if you need to specify
+Three optional arguments to :class:`~distutils.core.Extension` will help if you need to specify
 include directories to search or preprocessor macros to define/undefine:
 ``include_dirs``, ``define_macros``, and ``undef_macros``.