From b8f2ad03805048f43723019aecbcf181fbf01549 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 8 Jun 2011 00:47:49 +0200 Subject: [PATCH 1/4] Remove outdated bit of advice (584f9c213a6d follow-up) --- Doc/documenting/markup.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst index 57d9eeba147..c005d0c9e70 100644 --- a/Doc/documenting/markup.rst +++ b/Doc/documenting/markup.rst @@ -98,11 +98,12 @@ following example shows all of the features of this directive type:: 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: From b805c47138d23c2d6cbaffde81a4b7d9afe44e4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 8 Jun 2011 01:11:36 +0200 Subject: [PATCH 2/4] Add examples that work on Windows to distutils docs (#1626300) --- Doc/distutils/introduction.rst | 10 ++++++++-- Doc/install/index.rst | 15 +++++++++------ 2 files changed, 17 insertions(+), 8 deletions(-) diff --git a/Doc/distutils/introduction.rst b/Doc/distutils/introduction.rst index 8dc604d0d05..57d34a4b57e 100644 --- a/Doc/distutils/introduction.rst +++ b/Doc/distutils/introduction.rst @@ -79,11 +79,17 @@ Some observations: 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/install/index.rst b/Doc/install/index.rst index 31c1d7ff12e..f8d63057a6c 100644 --- a/Doc/install/index.rst +++ b/Doc/install/index.rst @@ -96,10 +96,16 @@ in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or 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 @@ Standard Build and Install ========================== 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: From 96deb7550effe961b2847a340ff05b1ab899d379 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 8 Jun 2011 04:53:20 +0200 Subject: [PATCH 3/4] Add links from builtins module docs to built-in functions and constants docs --- Doc/library/builtins.rst | 4 +++- Doc/library/constants.rst | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/Doc/library/builtins.rst b/Doc/library/builtins.rst index c4957289136..d4199d25f2d 100644 --- 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 index 51a1c262d68..fa61f68852b 100644 --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -1,3 +1,5 @@ +.. _built-in-consts: + Built-in Constants ================== From d2f8cec88558993e10c1dae103a5bae6549e25ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 8 Jun 2011 05:29:39 +0200 Subject: [PATCH 4/4] Fix a few misuses of :option: I missed in r86521. Extract of the commit message: Fix usage of :option: in the docs (#9312). :option: is used to create a link to an option of python, not to mark up any instance of any arbitrary command-line option. These were changed to ````. --- Doc/c-api/intro.rst | 4 ++-- Doc/license.rst | 4 ++-- Doc/using/cmdline.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index 83b98f9b4c2..843707df77a 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -588,8 +588,8 @@ frequently-used builds will be described in the remainder of this section. 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/license.rst b/Doc/license.rst index a32b7abeb6e..b4718281faf 100644 --- a/Doc/license.rst +++ b/Doc/license.rst @@ -845,7 +845,7 @@ expat ----- 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 @@ -874,7 +874,7 @@ libffi ------ 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 index d1f47eba897..16a753c0e35 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -501,7 +501,7 @@ Debug-mode variables ~~~~~~~~~~~~~~~~~~~~ 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